TikTok API for Business のアクセストークン:24 時間、更新と取り消し
TikTok API for Business のアクセストークンは 24 時間有効で、Access-Token ヘッダーで送信されます。アプリは、オーナーの認可コードを /tt_user/oauth2/token/ で交換して取得します。この交換では、1 年間有効なリフレッシュトークンも併せて取得できます。リフレッシュトークンを使うと、/tt_user/oauth2/refresh_token/ でアクセスを更新できます。取り消しは /tt_user/oauth2/revoke/ で行い、付与されたスコープの一覧は /tt_user/token_info/get/ で確認します。
easyCoexistence は、TikTok アカウントのサインイン時にコードを交換し、24 時間のトークンが切れる前に更新し、約 6 時間ごとにアカウントをチェックします。
TikTok アカウントのアクセストークンの有効期間です。各トークンのレスポンスには、expires_in に残りの秒数が記載されます。
それとともに発行されるリフレッシュトークンの有効期間です。refresh_token_expires_in に残りの秒数が示されます。
リダイレクトに含まれる認可コードが有効な期間です。交換できるのは 1 回だけです。
アカウントのアプリケーション固有の ID です。各トークンとともに返され、Accounts API の呼び出しで business_id として送信します。
TikTok が返す token_type です。トークンを保持している者であれば、誰でもそのアカウントのリソースにアクセスできます。
/tt_user/token_info/get/ がトークンのスコープとともに返すアカウント ID です。Accounts API の呼び出しで business_id として使えます。
認可コードはアプリにどう届きますか?
TikTok アカウント保有者の認可 URL を経由して届きます。この URL は、アプリが TikTok Accounts の権限を持つと、「My Apps」の「App Detail」、「Basic Information」から TikTok が生成します。アカウント所有者は URL を開き、権限を確認して承認します。すると TikTok は、ブラウザーをアプリのリダイレクト URL に移動させ、auth_code を付けます。認可 URL に state の値があれば、それも一緒に付きます。このコードは 10 分間有効で、交換できるのは 1 回だけです。
- リダイレクト URL:絶対 URL で、https:// で始まり、/ で終わり、クエリ文字列、アンカー、ポートを含まないこと。長さは 10〜512 文字です。
- アプリごとに最大 10 件のリダイレクト URL を登録できますが、有効にできるのは 1 件だけです。有効にすると、その URL 用の認可 URL が生成されます。
- state:任意の値で、リダイレクト時に TikTok がそのまま返します。CSRF 対策として推奨されています。
disable_auto_auth=1:以前に同じ権限を承認したオーナーにも、確認画面を表示させます。指定しないと、TikTok はそのようなオーナーをすぐにリダイレクトします。
コードをトークンに交換するにはどうしますか?
サーバーから JSON 形式で /tt_user/oauth2/token/ に POST します。client_id と client_secret には、「My Apps」の「App Detail」、「Basic Information」に表示される App ID と Secret を使います。grant_type は authorization_code、auth_code はリダイレクトで受け取ったコードです。redirect_uri は、アプリに設定した TikTok アカウント保有者のリダイレクト URL と一致させる必要があります。
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/token/' \
-H 'Content-Type: application/json' \
-d '{
"client_id": "<APP_ID>",
"client_secret": "<APP_SECRET>",
"grant_type": "authorization_code",
"auth_code": "<AUTH_CODE>",
"redirect_uri": "https://app.example.com/tiktok/callback/"
}'トークンのレスポンスには何が含まれますか?
code、message、request_id、data を含む JSON オブジェクトです。code が 0 なら交換は成功で、data に両方のトークンとアカウントの ID が入ります:
access_token:API 呼び出し用の短期トークンで、有効期間は 1 日です。token_type:Bearer です。TikTok によると、トークンを保持する者であれば誰でも使用できます。- scope:トークンに付与された権限で、カンマ区切りの 1 つの文字列です。
expires_in:アクセストークンの期限切れまでの残り秒数です。TikTok の例では 86400 です。refresh_token:アクセスを更新するためのトークンで、有効期間は 1 年です。TikTok は、保持しておくよう注意しています。refresh_token_expires_in:リフレッシュトークンの期限切れまでの残り秒数です。open_id:TikTok アカウントのアプリケーション固有の ID です。
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"access_token": "<ACCESS_TOKEN>",
"token_type": "Bearer",
"scope": "user.info.basic,user.info.stats,user.insights,video.list,video.insights,video.publish,comment.list,comment.list.manage",
"expires_in": 86400,
"refresh_token": "<REFRESH_TOKEN>",
"refresh_token_expires_in": 31536000,
"open_id": "<OPEN_ID>"
}
}API 呼び出しではトークンをどう送りますか?
Access-Token という名前のリクエストヘッダーで送ります。対象は /business/get/ から /business/video/publish/ までの Accounts API エンドポイントです。アカウント自体は business_id で指定し、同じレスポンスの open_id を設定します。OAuth のエンドポイントはこれと逆で、/tt_user/oauth2/token/、/tt_user/oauth2/refresh_token/、/tt_user/oauth2/revoke/ では、アプリの client_id と client_secret を JSON ボディで送り、Access-Token ヘッダーは使いません。
アクセストークンはどう更新しますか?
/tt_user/oauth2/refresh_token/ に POST します。送るのは client_id、client_secret、grant_type を refresh_token にした値、保存しておいた refresh_token です。レスポンスの項目は最初の交換と同じで、新しい access_token と expires_in、次回の更新に使う refresh_token、その残り秒数が返ります。エラー 40102 を待つのではなく、24 時間が経過する前に更新をスケジュールしてください。
import os, time, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def renew(refresh_token: str) -> dict:
r = requests.post(f"{API}/tt_user/oauth2/refresh_token/", json={
"client_id": os.environ["TIKTOK_APP_ID"],
"client_secret": os.environ["TIKTOK_APP_SECRET"],
"grant_type": "refresh_token",
"refresh_token": refresh_token,
}, timeout=30).json()
if r["code"] != 0: # 40103: the refresh token expired, so the owner authorizes again
raise RuntimeError(f"{r['code']}: {r['message']}")
d, now = r["data"], time.time()
return {
"access_token": d["access_token"],
"access_expires_at": now + d["expires_in"],
"refresh_token": d["refresh_token"], # keep it for the next renewal
"refresh_expires_at": now + d["refresh_token_expires_in"],
}アクセスを取り消すにはどうしますか?
アプリからは、/tt_user/oauth2/revoke/ に POST します。送るのは client_id、client_secret、取り消す access_token です。成功すると code 0 と空の data オブジェクトが返ります。アカウント側からは、所有者が TikTok アプリを開き、「Settings and privacy」、「Security」、「Manage app permissions」の順に進み、アプリを選んで「Remove access」を選びます。認可が取り消されると、TikTok はそのアカウントについて、アプリへの comment.update イベントの送信を停止します。
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/revoke/' \
-H 'Content-Type: application/json' \
-d '{"client_id": "<APP_ID>", "client_secret": "<APP_SECRET>", "access_token": "<ACCESS_TOKEN>"}'
# {"code": 0, "message": "OK", "request_id": "<REQUEST_ID>", "data": {}}トークンはどう確認しますか?
/tt_user/token_info/get/ に POST します。この API は独自の権限を必要としません。app_id と access_token を送ると、data に app_id、scope、creator_id が返ります。scope は所有者が付与した権限の一覧です。creator_id はアカウントのアプリケーション固有の ID で、Accounts API の呼び出しで business_id として指定する値です。TikTok のリファレンスは、フィールドにトークンが持たない可能性のあるスコープが必要な場合、ここを確認するよう案内しています。
トークン関連のエラーはどれですか?
TikTok はエラーをレスポンスの code フィールドに入れ、通常は HTTP ステータスコード 200 のもとで返します。呼び出しを信頼する前に code を確認してください。トークンとその交換に関連する戻りコードは次のとおりです:
- 40102:アクセストークンの期限が切れています。更新してから再度呼び出してください。
- 40103:リフレッシュトークンの期限が切れています。所有者による新たな認可でのみ置き換えられます。
- 40104:リクエストにアクセストークンが含まれていません。
- 40105:アクセストークンが無効または不正です。
- 40107:リフレッシュトークンが無効または不正です。例えば、有効期限のない Marketing API トークンを更新しようとして送った場合です。
- 40110:認可コードが取り消された、すでに使用された、または期限が切れています。
- 40131:2 つのトークンのエンドポイントで発生する認証エラーです。アプリ ID やシークレットの誤り、期限切れのコード、無効または期限切れのリフレッシュトークンが原因です。
easyCoexistence は何を更新しますか?
サインイン後のすべてです。easyCoexistence は、TikTok からリダイレクトされるとすぐにコードを交換し、両方のトークンを暗号化して保存します。また、アクセストークンも自動で更新します。残りが 15 分未満になった呼び出しの前に更新し、各アカウントに対して約 6 時間ごとに実行するチェックでは、残りが 8 時間未満の場合に更新します。更新のたびに新しいリフレッシュトークンとその期限が保存され、同時に届いた呼び出しは 1 回の更新を共有します。
- トークンの拒否:TikTok が 40102、40104 または 40105 を返すと、接続は再接続が必要な状態にマークされ、オーナーにメールが届きます。Partner API のユーザーには channel.disconnected も届きます。
- 独自のコードで取得する場合:
get_social_credentials、または Partner API の GET /channels/{id}?credentials=1 は、token_expires_atとともに現在のトークンを返します。そのため、ジョブごとに取得してください。 - 削除:ダッシュボードで接続を削除するか、DELETE /channels/{id} を使うと、/
tt_user/oauth2/revoke/ を通じて TikTok 側でトークンが取り消されます。
よくある間違い
- ブラウザーで認可コードを交換してしまうこと。交換ではアプリの client_secret が送られるため、リダイレクトから 10 分以内に、必ずサーバーから行ってください。
- expires_in を日付として読むこと。この値は残りの秒数なので、レスポンスを受け取った時刻に加算すると、トークンの期限切れ時刻が分かります。
- リフレッシュトークンで取り消すこと。/tt_user/oauth2/revoke/ が受け取るのは access_token で、アプリの client_id と client_secret も必要です。
- 同意画面が表示されないことを失敗とみなすこと。TikTok は、所有者が以前に承認した権限については確認画面を省略します。再表示するには disable_auto_auth=1 を付けてください。
そのため、Claude、ChatGPT、または独自のコードは、常に有効なトークンで TikTok を呼び出せます。そのトークンは get_social_credentials を通じてスクリプトに渡されます。接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。
よくある質問
TikTok API for Business のアクセストークンは、どれくらい有効ですか?
24 時間です。各トークンのレスポンスには、expires_in に残りの秒数が示されます。1 年間有効なリフレッシュトークンで更新できます。
TikTok のリフレッシュ用エンドポイントには redirect_uri が必要ですか?
パラメーター表には client_id、client_secret、grant_type、refresh_token が載っており、redirect_uri はありません。ただし、TikTok の認証ガイドでは、トークンのエンドポイントには redirect_uri が必要と書かれています。
TikTok のトークンを取り消すと、Webhook も止まりますか?
はい。所有者が再度アプリを認可するまで、TikTok はそのアカウントについてアプリへの comment.update イベントを送信しません。
TikTok の business_id はどこから得られますか?
トークンのレスポンスの open_id です。Accounts API の呼び出しでは、これを business_id として指定します。/tt_user/token_info/get/ も、同じ ID を creator_id として返します。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日