最終更新 2026年11月1日

認証

すべてのリクエストには、ワークスペースの API キーを Bearer トークンとして付与します。キーはスコープ付きで失効でき、ひとつのワークスペースのクレジットウォレットに紐づきます。

Bearer キー

キーは Authorization ヘッダーに Bearer <key> の形式で送信します。キーは ttk_live_<id>_<secret> の形式で、ダッシュボードでは ttk_live_<id> のプレフィックスで一覧表示されます。キーは 設定 → API キー で作成でき、完全なキーが表示されるのは一度だけです。キーはワークスペースのオーナーとして動作し、その権限はキーのスコープの範囲に限られます。

curl "https://api.toktokdata.live/v1/rankings/regions" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

ウォレットはひとつ

キーは、そのキーを所有するワークスペースのクレジットを消費します。API とダッシュボードの使用量は、まとめて 設定 → 使用量 に表示されます。

スコープ

キーが呼び出せるのは、そのスコープに含まれるエンドポイントだけです。用途を満たす最小限のスコープを選んでください。キーはいつでも追加で作成できます。キーのスコープ外のリクエストや、ダッシュボード専用のルート（ウォッチリスト、ルーム、ワークスペース、請求）は、コード insufficient_scope とともに 403 を返します。モジュールを含まないプランの場合は module_not_entitled が返ります。

スコープ	許可される操作
`live:read`	LIVE セッション一覧、個別のセッション、クリエイターのパフォーマンス、ライブ状態の更新。LIVE モジュールが必要です。
`rank:read`	公式ランキング、地域、ランキングの履歴。LIVE モジュールが必要です。
`shop:read`	ショッピングランキング（board が shopping で始まるもの）にも必要です。
`creator:read`	クリエイターの検索、プロフィール、分析、変更履歴、フォロー中、フォロワー、インサイト。検索モジュールが必要です。
`content:read`	動画、動画のコメント、クリエイターの動画一覧。検索モジュールが必要です。
`trend:read`	地域別トレンド。検索モジュールが必要です。
`export`	エクスポートの作成、一覧、ダウンロード。
`webhook:manage`	すべてのチャネルのアラートルールと、ルールのテスト。LIVE モジュールが必要です。
`keys:manage`	API キーの一覧、作成、失効。利用権限と使用量の読み取り。
`live:stream · gifter:read`	今後追加するエンドポイント用に予約済みです。現時点では何も許可しません。

キーのローテーション

まず新しいキーを作成してデプロイし、そのあと同じ画面から古いキーを失効させます。失効は即時に反映されます。処理中のリクエストは完了しますが、新しいリクエストは 401 で失敗します。

キーには有効期限（expiresAt）を設定して作成することもできます。期限を過ぎたキーは 401 を返します。

エラー

ステータス	コード	意味
401	`unauthorized`	キーがない、形式が不正、失効済み、期限切れ、またはワークスペースが無効です。
403	`insufficient_scope`	キーは有効ですが必要なスコープがない、またはダッシュボード専用のルートです。
403	`module_not_entitled`	ワークスペースのプランに LIVE モジュールまたは検索モジュールが含まれていません。
402	`credit_cap_exceeded`	今月のクレジットを使い切りました。クレジットとエラーを参照してください。

このページは役に立ちましたか？