Telm のすべての API リクエストは、tk_live_ で始まる API キー で認証されます。ダッシュボードのログインでは決してありません。アカウントでキーを作成し、Authorization ヘッダーに Bearer トークンとして送ると、あなたが管理者であるグループについて、あなたのアカウントを代理して動作します。キーが漏れたら、ダッシュボードで取り消して新しいものを発行してください。
1API キーの仕組み
Telm REST API は、ブラウザのセッションを使いません。代わりに、各リクエストは API キー、つまり接頭辞 tk_live_ にランダムな文字が続く長い秘密文字列を持ちます。キーはあなたのアカウントを識別し、呼び出しを認可します。
キーはアカウントから生成し、一度に複数保持できます(たとえばスクリプトやサービスごとに 1 つ)。完全な秘密は作成時に一度だけ表示されます。その後、ダッシュボードはキーを短い接頭辞(tk_live_ と最初の文字)で一覧し、識別できるようにしますが、完全な値はそれ以降決して保持されません。
- キーは tk_live_ に長いランダム文字列が続く形をしています。
- キーは ダッシュボード で作成・管理します。
- 完全な秘密は一度だけ表示されます。すぐにコピーして安全な場所に保管してください。
- キーはパスワードのように扱ってください。それを持つ者は誰でも、あなたとして API を呼び出せます。
2すべてのリクエストでキーを送る
Bearer スキームを使って Authorization ヘッダー でキーを渡します。ヘッダーの値は、Bearer という語、スペース、そしてあなたのキーです。たとえば Authorization: Bearer tk_live_your_key_here です。
Authorization ヘッダーを手軽に設定できないクライアントのために、API は X-API-Key ヘッダーでのキーも受け付けます。両方あれば Authorization ヘッダーが優先されます。本番では HTTPS 以外のものを介したリクエストは受け付けられません。
- 推奨:Authorization: Bearer tk_live_... を送ります。
- 代替:代わりに X-API-Key ヘッダーでキーを送ります。
- すべての呼び出しのベース URL は api.telm.com/api/public/v1 です。
- エンドポイントの完全な一覧とスキーマは developers ページ を参照してください。
3キーがアクセスできるもの
キーは厳密にあなたのアカウントを代理して動作します。あなたのアカウントが管理者であるグループのみを読み書きできます。他のグループを対象とするリクエストは 404 を返すため、API はあなたが管理できないグループの存在すら決して明かしません。
アクセスは対象グループのプランにも依存します。スパム判定エンドポイントは日次の枠内であればすべてのプランに開かれており、フル API(ルール・設定・ホワイトリスト・ジャーナル・分析・バッチ判定・Webhook)は、関わるグループが Pro プラン以上の場合に利用できます。
- キーは、あなたが管理者であるグループにのみ触れられます。
- あなたが管理しないグループへのリクエストは、403 ではなく 404 を返します。
- 日次の枠はあなたのすべてのキーで共有され、アカウントごとに数えられます。
4キーの取り消しとローテーション
キーが露出したら、つまりリポジトリにコミットされた、チャットに貼られた、あるいは他のどんな形であれ漏れたら、ダッシュボードから すぐに取り消して ください。取り消しはただちに効きます。取り消されたキーは、何らかの遅延の後ではなく、数秒以内に動かなくなります。
日次の枠はアカウントごとに共有されるため、1 つのキーを取り消しても使用カウンターはリセットされません。キーを定期的にローテーションするのは良い衛生です。新しいキーを作成し、サービスへ配備し、動作を確認してから、古いものを取り消せば、ダウンタイムがありません。
- ダッシュボード からキーを取り消します。ほぼ即座に動かなくなります。
- まず置き換えを作成し、展開してから、古いキーを取り消せば、ダウンタイムなしでローテーションできます。
- キーの取り消しは日次の枠をリセットしません。それは UTC 深夜にリセットされます。
5認証エラー
欠けた、形式が不正な、または取り消されたキーは、機械可読なエラー コードと人間可読なメッセージとともに 401 を返します。リクエストが突然 401 で失敗し始めたら、キーが取り消されていないか、そして Authorization ヘッダーが Bearer とスペースとキーのとおり正確に綴られているか確認してください。
あなたが管理しないグループを対象とする有効なキーは 404 を返します。Pro 未満のプランで Pro 専用エンドポイントを呼ぶ有効なキーは、plan_required コードとアップグレードのヒントとともに 403 を返します。
- 401 — キーが欠けている、形式が不正、または取り消されている。
- 404 — 対象グループが存在しないか、あなたがその管理者でない。
- 403 plan_required — そのグループでエンドポイントに Pro 以上が必要。