TKBADA API documentation

TKBADA is an API gateway for merchant advertising teams and their service integrations. External clients create an account, connect TikTok for Business through official OAuth, and use their own API key to send requests from their tools. The console manages connections, keys and call records; business operations are requested through the API.

See Permissions & intended uses for the 26 groups in our application, their merchant workflows, data and authorization boundaries.

Overview

Paths map one to one: https://api.tkbada.com/v1.3/<path> calls https://business-api.tiktok.com/open_api/v1.3/<path>. Request parameters and response fields are exactly those of the TikTok API for Business documentation.

Quick start

1. Create a TKBADA account and verify your work email with the 6-digit code we send.
2. In the console, click Connect TikTok account and approve the authorization on TikTok.
3. Create an API key in the console and store it securely.
4. Choose an endpoint covered by your granted permissions and call it with the key and your connected advertiser ID. The examples below illustrate request formats:

curl "https://api.tkbada.com/v1.3/campaign/get/?advertiser_id=7000000000000000000&page_size=10" \
  -H "Authorization: Bearer tkb_live_xxxxxxxxxxxxxxxx"

Retrieve a daily campaign report with the required reporting permission:

curl --get https://api.tkbada.com/v1.3/report/integrated/get/ \
  -H "Authorization: Bearer tkb_live_xxxxxxxxxxxxxxxx" \
  --data-urlencode 'advertiser_id=YOUR_ADVERTISER_ID' \
  --data-urlencode 'report_type=BASIC' \
  --data-urlencode 'data_level=AUCTION_CAMPAIGN' \
  --data-urlencode 'dimensions=["campaign_id","stat_time_day"]' \
  --data-urlencode 'metrics=["spend","impressions","clicks"]' \
  --data-urlencode 'start_date=2026-10-01' \
  --data-urlencode 'end_date=2026-10-07'

Use reports in your service tools to review the authorizing merchant's advertising performance. Examples and sample responses are documentation, not evidence that an account has received a permission.

Accounts & API keys

• Each TKBADA account can hold up to 10 active API keys. Keys start with tkb_live_.
• A key is displayed only once when created. TKBADA stores only a SHA-256 hash of it.
• Revoke a key at any time from the console; revoked keys stop working immediately.
• A key can only reach the TikTok accounts connected to the same TKBADA account.

Connecting TikTok accounts

TKBADA uses TikTok for Business's official OAuth flow. No TikTok passwords are ever shared with us.

1. The signed-in user opens https://www.tkbada.com/oauth/start (the Connect TikTok account button).
2. TKBADA redirects to TikTok's authorization page with a signed, time-limited state value.
3. The user reviews the requested permissions and selects the ad accounts to authorize.
4. TikTok redirects to https://www.tkbada.com/oauth/callback with an auth_code.
5. TKBADA exchanges the code for an access token, encrypts it (AES-256-GCM) and records the authorized advertiser IDs.

A user may connect several authorizations. Disconnecting one in the console stops all API access through it. Users can also revoke TKBADA's access directly in TikTok for Business.

Authentication

Send your key in the Authorization header on every request:

Authorization: Bearer tkb_live_xxxxxxxxxxxxxxxx

Do not send a TikTok Access-Token header; TKBADA attaches the correct access token of the user's connection. Never expose API keys in browsers or mobile apps; call TKBADA from your server.

Making requests

• Use the same HTTP method, path, query string and body as the TikTok API for Business documentation.
• Paths must end with a slash, for example /v1.3/adgroup/get/. TKBADA adds it if missing.
• JSON bodies are limited to 10 MB. Uploads are streamed and limited to 500 MB.
• Every response carries an X-TKBADA-Request-Id header; include it when contacting support.
• GET https://api.tkbada.com/v1.3 returns service information and the number of supported endpoints.

Choosing the advertiser

TKBADA selects a connection belonging to the caller. Requests containing advertiser IDs are checked against that connection's authorized advertisers. TikTok also enforces the access token's permissions for other assets:

File uploads

curl -X POST https://api.tkbada.com/v1.3/file/image/ad/upload/ \
  -H "Authorization: Bearer tkb_live_xxxxxxxxxxxxxxxx" \
  -H "X-Advertiser-Id: 7000000000000000000" \
  -F "advertiser_id=7000000000000000000" -F "upload_type=UPLOAD_BY_FILE" \
  -F "image_signature=<md5>" -F "image_file=@banner.png"

For multipart requests TKBADA does not read the form fields, so pass the advertiser in the X-Advertiser-Id header.

Responses

Successful gateway calls return TikTok's response unchanged, including the HTTP status and TikTok's envelope:

{ "code": 0, "message": "OK", "request_id": "202609250000000000000000", "data": { ... } }

A non-zero code is a TikTok business error; see TikTok's error code list. Errors raised by TKBADA itself use this format:

{ "error": { "code": "advertiser_not_connected", "message": "Advertiser 7000... is not connected to your TKBADA account" } }

Errors

Rate limits

Each API key may send 10 requests per second with bursts up to 20. TikTok's own per-app and per-advertiser limits also apply; when TikTok throttles a call, its response is passed through unchanged. Use exponential backoff on 429 and on TikTok rate-limit codes.

Security & data

• Stored connection tokens are encrypted at rest with AES-256-GCM and are not exposed by the console.
• API keys are stored as SHA-256 hashes; passwords are stored with bcrypt.
• API keys and connections belong to a TKBADA account. Advertiser IDs supplied in requests are checked against that account's connected advertisers; TikTok enforces upstream permissions.
• The application call log stores metadata (time, method, endpoint, advertiser ID, status, duration), not request or response bodies.
• We do not sell or rent TikTok data. Processing and disclosure are described in the Privacy Policy.

Portal API

The console uses these endpoints with a session cookie. They are documented for transparency; integrations should use API keys and the gateway.

Changelog

• 2026-10-08: Added the 26-group intended-use guide; clarified external client access, permission-dependent availability and the data processed by the gateway.
• 2026-09-25: Introduced the v1.3 gateway catalog, OAuth connections, API keys and call logs.