TikTok Open SDK

A comprehensive Ruby SDK for integrating with TikTok Open API. This gem provides OAuth 2.0 authentication, user authorization, and HTTP client functionality for accessing TikTok APIs seamlessly.

Features

OAuth 2.0 Authentication – Seamless OAuth flow for secure integration
OmniAuth Strategy – Ready-to-use OmniAuth strategy for Rails applications
Client Authentication – Server-to-server authentication with client credentials
Token Management – Easy access token exchange and refresh
User API – Convenient methods to access user information
Post API – Methods for querying creator information and video publishing
HTTP Client – Built-in client for interacting with TikTok APIs

Installation

Add this line to your application's Gemfile:

gem 'tiktok-open-sdk'

And then execute:

bundle install

Or install it directly:

gem install tiktok-open-sdk

Configuration

Before using the SDK, you need to configure it with your TikTok app credentials:

require 'tiktok/open/sdk'

Tiktok::Open::Sdk.configure do |config|
  # Required: Your TikTok app credentials
  config.client_key    = 'your_client_key'
  config.client_secret = 'your_client_secret'
  
  # Optional: Customize OAuth settings
  config.user_auth.scopes       = %w[user.info.basic video.list]
  config.user_auth.redirect_uri = 'https://your-app.com/auth/callback'
  
  # Optional: Custom URLs (defaults are provided)
  config.user_auth.auth_url         = 'https://www.tiktok.com/v2/auth/authorize/'
  config.user_auth.token_url        = 'https://open.tiktokapis.com/v2/oauth/token/'
  config.user_auth.revoke_token_url = 'https://open.tiktokapis.com/v2/oauth/revoke/'
  config.user_info_url              = 'https://open.tiktokapis.com/v2/user/info/'
  config.creator_info_query_url     = 'https://open.tiktokapis.com/v2/post/publish/creator_info/query/'

  # Optional: Enable OmniAuth strategy auto-loading
  config.load_omniauth = true
end

Getting TikTok App Credentials

Visit TikTok for Developers
Create a new app or use an existing one
Navigate to your app's settings
Copy your Client Key and Client Secret

Usage

Basic OAuth Flow

1. Generate Authorization URI

# Generate the authorization URI for user login
auth_uri = Tiktok::Open::Sdk.user_auth.authorization_uri

# Or with custom parameters
auth_uri = Tiktok::Open::Sdk.user_auth.authorization_uri(
  scope:        'user.info.basic,video.list',
  redirect_uri: 'https://your-app.com/callback',
  state:        'random_state_string'
)

puts auth_uri.to_s
# => "https://www.tiktok.com/v2/auth/authorize/?client_key=your_key&response_type=code&scope=user.info.basic&redirect_uri=https://your-app.com/callback"

2. Handle Authorization Callback

After the user authorizes your app, TikTok will redirect to your redirect_uri with an authorization code:

# Extract the code from the callback URL
code = params[:code] # From your web framework (Rails, Sinatra, etc.)

# Exchange the code for an access token
response = Tiktok::Open::Sdk.user_auth.fetch_access_token(code: code)

if response[:success]
  access_token  = response[:response][:access_token]
  refresh_token = response[:response][:refresh_token]
  expires_in    = response[:response][:expires_in]
  
  puts "Access Token: #{access_token}"
  puts "Refresh Token: #{refresh_token}"
  puts "Expires in: #{expires_in} seconds"
else
  puts "Error: #{response[:response]}"
end

3. Refresh Access Token

# Refresh an expired access token
response = Tiktok::Open::Sdk.user_auth.refresh_access_token(
  refresh_token: 'your_refresh_token'
)

if response[:success]
  new_access_token = response[:response][:access_token]

  puts "New Access Token: #{new_access_token}"
end

4. Revoke Access Token

# Revoke a refresh token
response = Tiktok::Open::Sdk.user_auth.revoke_access_token(
  token: 'your_refresh_token'
)

puts "Token revoked successfully" if response[:success]

Client Authentication

For server-to-server authentication, you can obtain a client access token:

# Fetch client access token
response = Tiktok::Open::Sdk.client_auth.fetch_client_token

if response[:success]
  client_token = response[:response][:access_token]
  expires_in   = response[:response][:expires_in]
  
  puts "Client Token: #{client_token}"
  puts "Expires in: #{expires_in} seconds"
else
  puts "Error: #{response[:response]}"
end

Note: Client tokens are used for server-to-server authentication and have different scopes and permissions than user tokens.

Using the Post API

The SDK provides convenient methods for interacting with TikTok's Post API:

Creator Info Query

Query creator information for video publishing:

# Get creator information
response = Tiktok::Open::Sdk.post.creator_info_query(access_token: access_token)

if response[:success]
  creator_data = response[:response][:data]

  puts "Creator Avatar: #{creator_data[:creator_avatar_url]}"
  puts "Creator Nickname: #{creator_data[:creator_nickname]}"
  puts "Max Video Duration: #{creator_data[:max_video_post_duration_sec]} seconds"
  puts "Privacy Options: #{creator_data[:privacy_level_options]}"
else
  puts "Error: #{response[:response][:error][:message]}"
end

Using the User API

The SDK provides a convenient way to access user information:

# Get user information
response = Tiktok::Open::Sdk.user.get_user_info(
  access_token: access_token,
  fields: %w[open_id union_id avatar_url display_name]
)

if response[:success]
  user_data = response[:response][:data][:user]
  
  puts "User ID: #{user_data[:open_id]}"
  puts "Display Name: #{user_data[:display_name]}"
else
  puts "Error: #{response[:response][:error][:message]}"
end

Available user fields include:

open_id - User's Open ID
union_id - User's Union ID
avatar_url - User's avatar URL
display_name - User's display name
username - User's username
And more (see documentation for full list)

Using OmniAuth Strategy

The SDK provides a ready-to-use OmniAuth strategy for Rails applications:

Rails Setup

Add the OmniAuth strategy to your Rails application:

# config/initializers/devise.rb
Devise.setup do |config|
  config.omniauth(
    :tiktok_open_sdk,
    Rails.application.credentials.dig(:tiktok, :client_key),
    Rails.application.credentials.dig(:tiktok, :client_secret),
    scope:         'user.info.basic,user.info.profile,user.info.stats',
  )
end

Or use the SDK configuration:

# config/initializers/tiktok_sdk.rb
Tiktok::Open::Sdk.configure do |config|
  config.client_key             = Rails.application.credentials.dig(:tiktok, :client_key)
  config.client_secret          = Rails.application.credentials.dig(:tiktok, :client_secret)
  config.user_auth.scopes       = %w[user.info.basic video.publish]
  config.user_auth.redirect_uri = "#{Rails.application.config.action_mailer.asset_host.chomp('/')}/users/auth/tiktok_open_sdk/callback"
  config.load_omniauth          = true
end

OmniAuth Callback

Handle the OmniAuth callback in your controller:

# app/controllers/omniauth_callbacks_controller.rb
class OmniauthCallbacksController < Devise::OmniauthCallbacksController
  def tiktok_open_sdk
    @auth = request.env['omniauth.auth']

    # Find or create user based on TikTok auth data
    @user = User.find_for_oauth(@auth)

    # ...

    if @user.persisted?
      sign_in_and_redirect @user, event: :authentication
      set_flash_message :notice, :success, kind: 'TikTok'
    else
      session['devise.provider_data'] = @auth.except('extra')
      redirect_to new_user_registration_url
    end
  end
end

Supported Scopes

The OmniAuth strategy supports the following TikTok scopes:

user.info.basic - Basic user info: open_id, union_id, display_name, avatar URLs
user.info.profile - Profile info: username, bio_description, profile_deep_link, is_verified
user.info.stats - Statistics: follower_count, following_count, likes_count, video_count

Using the HTTP Client

The SDK includes a flexible HTTP client for making API calls:

# GET request using request method
response = Tiktok::Open::Sdk::HttpClient.request(
  :get,
  'https://open.tiktokapis.com/v2/user/info/',
  params: {
    fields: 'open_id,union_id,avatar_url'
  },
  headers: {
    'Authorization' => "Bearer #{access_token}"
  }
)

# GET request using get method
response = Tiktok::Open::Sdk::HttpClient.get(
  'https://open.tiktokapis.com/v2/user/info/',
  params: {
    fields: 'open_id,union_id,avatar_url'
  },
  headers: {
    'Authorization' => "Bearer #{access_token}"
  }
)

# POST request
response = Tiktok::Open::Sdk::HttpClient.post(
  'https://open.tiktokapis.com/v2/video/list/',
  headers: {
    'Authorization' => "Bearer #{access_token}",
    'Content-Type'  => 'application/json'
  },
  body: {
    # ...
  }
)

# Check response
if response.is_a?(Net::HTTPSuccess)
  data = JSON.parse(response.body)

  puts "Success: #{data}"
else
  puts "Error: #{response.code} - #{response.body}"
end

Complete Rails Example

Here's a complete example for a Rails application:

# config/initializers/tiktok_sdk.rb
require 'tiktok/open/sdk'

Tiktok::Open::Sdk.configure do |config|
  config.client_key             = Rails.application.credentials.tiktok_client_key
  config.client_secret          = Rails.application.credentials.tiktok_client_secret
  config.user_auth.scopes       = %w[user.info.basic video.list]
  config.user_auth.redirect_uri = "#{Rails.application.routes.url_helpers.root_url}auth/tiktok/callback"
end

# app/controllers/tiktok_auth_controller.rb
class TiktokAuthController < ApplicationController
  def login
    # Generate authorization URI
    auth_uri = Tiktok::Open::Sdk.user_auth.authorization_uri(
      state: session[:state] = SecureRandom.hex(16)
    )
    
    redirect_to auth_uri.to_s
  end
  
  def callback
    # Verify state parameter for CSRF protection
    if params[:state] != session[:state]
      redirect_to root_path, alert: 'Invalid state parameter'

      return
    end
    
    # Exchange code for access token
    response = Tiktok::Open::Sdk.user_auth.fetch_access_token(code: params[:code])
    
    if response[:success]
      token_data = response[:response]
      
      # Store tokens securely (consider using encrypted attributes)
      session[:tiktok_access_token]  = token_data[:access_token]
      session[:tiktok_refresh_token] = token_data[:refresh_token]
      
      # Fetch user information
      user_response = Tiktok::Open::Sdk::OpenApi::User.get_user_info(
        access_token: token_data[:access_token],
        fields: %w[open_id display_name avatar_url]
      )
      
      if user_response[:success]
        user_data = user_response[:response][:data][:user]
        session[:tiktok_user_name] = user_data[:display_name]
        session[:tiktok_avatar] = user_data[:avatar_url]
      end
      
      redirect_to dashboard_path, notice: 'Successfully connected to TikTok!'
    else
      redirect_to root_path, alert: 'Failed to authenticate with TikTok'
    end
  end
  
  def disconnect
    if session[:tiktok_refresh_token]
      Tiktok::Open::Sdk.user_auth.revoke_access_token(
        token: session[:tiktok_refresh_token]
      )
    end
    
    session.delete(:tiktok_access_token)
    session.delete(:tiktok_refresh_token)
    
    redirect_to root_path, notice: 'Disconnected from TikTok'
  end
end

API Reference

Configuration

`Tiktok::Open::Sdk.configure`

Configures the SDK with your app credentials and settings.

Tiktok::Open::Sdk.configure do |config|
  config.client_key             = 'your_client_key'    # Required
  config.client_secret          = 'your_client_secret' # Required
  config.user_auth.scopes       = %w[user.info.basic]  # Optional
  config.user_auth.redirect_uri = 'https://...'        # Optional
  config.user_info_url          = 'https://open.tiktokapis.com/v2/user/info/' # Optional
end

User Authentication

`authorization_uri(params = {})`

Generates the OAuth authorization URI.

Parameters:

scope (String, optional) - Comma-separated scopes
redirect_uri (String, optional) - Custom redirect URI
state (String, optional) - State parameter for CSRF protection

Returns: URI object

`fetch_access_token(code:, redirect_uri: nil)`

Exchanges authorization code for access token.

Parameters:

code (String, required) - Authorization code from callback
redirect_uri (String, optional) - Redirect URI used in authorization

Returns: Hash with :success, :code, and :response keys

`refresh_access_token(refresh_token:)`

Refreshes an expired access token.

Parameters:

refresh_token (String, required) - Refresh token

Returns: Hash with :success, :code, and :response keys

`revoke_access_token(token:)`

Revokes a refresh token.

Parameters:

token (String, required) - Refresh token to revoke

Returns: Hash with :success, :code, and :response keys

Client Authentication

`fetch_client_token`

Obtains a client access token for server-to-server authentication.

Returns: Hash with :success, :code, and :response keys

Example Response:

{
  success:  true,
  code:     200,
  response: {
    access_token: "client_token_here",
    expires_in:   7200,
    token_type:   "Bearer"
  }
}

User API

`get_user_info(access_token:, fields:, validate: true)`

Retrieves user information from the TikTok Open API.

Parameters:

access_token (String, required) - OAuth2 access token for authentication
fields (Array, required) - User fields to retrieve (must be valid fields)
validate (Boolean, optional) - Whether to validate the token and fields (default: true)

Returns: Hash with :success, :code, and :response keys

Available Fields:

open_id - Unique identifier for the user within the current application
union_id - Persistent identifier for the user across different applications from the same developer
avatar_url - URL to the user's profile image
avatar_url_100 - URL to the user's profile image in 100x100 pixel size
avatar_large_url - URL to the user's profile image in higher resolution
display_name - User's display name shown on their TikTok profile
bio_description - User's biography text (if available)
profile_deep_link - Direct link to the user's TikTok profile page
is_verified - Boolean indicating if the account is verified by TikTok
username - User's unique TikTok username
follower_count - Number of followers the user has
following_count - Number of accounts the user is following
likes_count - Total number of likes received across all user's videos
video_count - Total number of publicly posted videos by the user

Post API

`creator_info_query(access_token:)`

Queries creator information from the TikTok Open API for video publishing.

Parameters:

access_token (String, required) - OAuth2 access token for authentication

Returns: Hash with :success, :code, and :response keys

Response Data:

creator_avatar_url - Creator's avatar URL
creator_nickname - Creator's display name
creator_username - Creator's username
stitch_disabled - Whether stitch is disabled for the creator
comment_disabled - Whether comments are disabled for the creator
duet_disabled - Whether duet is disabled for the creator
max_video_post_duration_sec - Maximum video duration in seconds
privacy_level_options - Available privacy level options

HTTP Client

`request(method, url, params: {}, headers: {}, body: nil)`

Performs HTTP requests.

Parameters:

method (Symbol) - HTTP method (:get, :post)
url (String) - Request URL
params (Hash, optional) - Query parameters
headers (Hash, optional) - HTTP headers
body (Hash, optional) - Request body

Returns: Net::HTTPResponse object

`get(url, params: {}, headers: {})`

Convenience method for GET requests.

Parameters:

url (String) - Request URL
params (Hash, optional) - Query parameters
headers (Hash, optional) - HTTP headers

Returns: Net::HTTPResponse object

`post(url, params: {}, headers: {}, body: nil)`

Convenience method for POST requests.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Running Tests

# Run all tests
bundle exec rspec

# Run tests with coverage
bundle exec rspec --format documentation

Code Quality

This project uses RuboCop for code quality:

# Check code style
bundle exec rubocop

# Auto-fix issues
bundle exec rubocop -a

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/pochkuntaras/tiktok-open-sdk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/your-username/tiktok-open-sdk.git
Install dependencies: bundle install
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Run tests: bundle exec rspec
Check code style: bundle exec rubocop
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature-name
Submit a pull request

License

The gem is available as open source under the terms of the MIT License.

Changelog

See CHANGELOG.md for a list of changes and version history.

tiktok-open-sdk

TikTok Open SDK

Features

Installation

Configuration

Getting TikTok App Credentials

Usage

Basic OAuth Flow

1. Generate Authorization URI

2. Handle Authorization Callback

3. Refresh Access Token

4. Revoke Access Token

Client Authentication

Using the Post API

Creator Info Query

Using the User API

Using OmniAuth Strategy

Rails Setup

OmniAuth Callback

Supported Scopes

Using the HTTP Client

Complete Rails Example

API Reference

Configuration

Tiktok::Open::Sdk.configure

User Authentication

authorization_uri(params = {})

fetch_access_token(code:, redirect_uri: nil)

refresh_access_token(refresh_token:)

revoke_access_token(token:)

Client Authentication

fetch_client_token

User API

get_user_info(access_token:, fields:, validate: true)

Post API

creator_info_query(access_token:)

HTTP Client

request(method, url, params: {}, headers: {}, body: nil)

get(url, params: {}, headers: {})

post(url, params: {}, headers: {}, body: nil)

Development

Running Tests

Code Quality

Contributing

Development Setup

License

Links

Changelog

`Tiktok::Open::Sdk.configure`

`authorization_uri(params = {})`

`fetch_access_token(code:, redirect_uri: nil)`

`refresh_access_token(refresh_token:)`

`revoke_access_token(token:)`

`fetch_client_token`

`get_user_info(access_token:, fields:, validate: true)`

`creator_info_query(access_token:)`

`request(method, url, params: {}, headers: {}, body: nil)`

`get(url, params: {}, headers: {})`

`post(url, params: {}, headers: {}, body: nil)`