APIキー
Tiro APIは認証にAPIキーを使用します。すべてのAPIリクエストには、Bearerトークン形式を用いて、Authorizationヘッダーに有効なAPIキーを含める必要があります。 各キーは 1 つのワークスペースに属します。キーはそのワークスペースのリソース(ノート、トランスクリプト、サマリー、フォルダ)にのみ到達し、その外には届きません。先にワークスペースを選んでから、キーを作成してください。キーの種類と権限
Tiro API keyは、リクエストの主体によって2種類に分かれます。
ワークスペースシステムキーは、ワークスペースの全メンバーに共有されたフォルダに入っているノートのみを読み取ります。個人フォルダにあるノート、一部のメンバーにだけ共有したフォルダのノート、どのフォルダにも入れていないノートは、読み取り範囲から外れます。それらのノートも読み取る必要がある場合や、Voice File Jobのライフサイクル以外でデータの作成・更新・削除が必要な場合は、ユーザーキーを作成して使用してください。
移行期間について。 この読み取り範囲が適用される前に作成されたワークスペースシステムキーは、当面これまでの動作を維持し、順次移行される予定です。そのため、新しく作成したキーが以前のキーより少ないノートを返すことがありますが、これは正常な動作です。キーの種類ごとの読み取り範囲と、読み取れないノートがどのようなレスポンスになるかは、システムキーが読み取るノートの範囲にまとめています。
ワークスペースシステムキーがまだワークスペースに紐づいていない場合、認証は
401 Unauthorizedで失敗することがあります。キー形式が正しいのに401が続く場合は、キーが接続されているワークスペースと作成画面を先に確認してください。スコープ (Scope)
スコープはキーがどの操作を行えるかを絞り込む最小権限の設定です。発行時に選択でき、発行後に変更することもできます。- スコープを指定しないキーは、今後追加される API を含むすべての操作を行えます。 最小権限が必要な場合は、キーに必要なスコープを明示してください。スコープは権限を付与するのではなく絞り込むためのもので、指定したスコープに対応する API のみ呼び出せます。それ以外は
403 insufficient_scopeで拒否されます。 writeスコープは同じリソースのreadを含みます。 たとえばnote:writeのみを指定したキーでも、note:readが必要な読み取り API を呼び出せます。- スコープはすべてのキー種別(ユーザー・ワークスペース・組織)に適用されます。
- 選択可能なスコープ一覧は
GET /v1/api-key-scopesで取得できます。
スコープ一覧
API ごとに必要なスコープ
スコープを指定したキーは、そのスコープを持つ API のみ呼び出せます。スコープを指定しないキーはすべての API を呼び出せます。API keyを取得する
API keyはTiro Platformダッシュボードから取得できます。1
Sign in
platform.tiro.ooo/dashboard/api-keysにアクセスします。
2
Pick a workspace
サイドバーのワークスペース切り替えで、キーがアクセスするデータのワークスペースを選びます。キーはこのワークスペースのみに限定されます。
3
Create a key
Create New API Key をクリックし、名前を付けてから、ドットを含むfull keyをコピーします —
abc123.xR7mK9pL2qW4...。4
Store it
環境変数として保存します。secretは一度だけ表示され、ダイアログを閉じると復元できません。
API key形式
Tiro APIのkeyは次の形式に従います。abc123.xR7mK9pL2qW4...
認証付きリクエストを行う
すべてのリクエストのAuthorizationヘッダーにAPI keyを含めます。
認証エラー
認証に失敗すると、401 Unauthorizedレスポンスが返されます。主な原因は次のとおりです。
- Authorizationヘッダーがない
- keyの形式が不正(
{id}.{secret}である必要があります) - 不明なkey id
- 無効、期限切れ、または削除されたkey
レガシー個人キー(非推奨)
ワークスペース導入より前は、個人API キーはワークスペースではなくアカウントに紐づいていました。これらの個人キーは非推奨です。チームキーは現在ワークスペースキーとして渡されます — 各チームが 1 つのワークスペースに対応します。ワークスペースキーが個人キーとチームキーの両方を置き換えます。
形式は同一なので、移行は 1 行の差し替えで済みます — コードの書き換えは不要です。
3 ステップで移行する
1
Create a workspace key
ダッシュボードで、連携が使用するノートを含むワークスペースを選択し、キーを作成します。
2
Swap the secret
TIRO_API_KEY環境変数の値を新しいキーに置き換えます。ほかのコード変更は必要ありません。3
Revoke the legacy key
新しいキーでトラフィックが流れることを確認したら、ダッシュボードのLegacy personal keysセクションからレガシーキーを削除します。
レガシーキーはアカウント上のすべてのノートに到達しましたが、ワークスペースキーは 1 つのワークスペースにのみ到達します。データが複数のワークスペースにまたがる場合は、ワークスペースごとにキーを 1 つずつ作成してください。
セキュリティのベストプラクティス
環境変数
環境変数を使用して、API keyを安全に保管します。その他のセキュリティガイドライン
- keyを定期的にローテーションする: 使用していないkeyを削除し、新しいkeyを生成します
- 環境ごとにkeyを分ける: 開発環境と本番環境で異なるkeyを使用します
- 利用状況を監視する: API keyの利用状況を追跡し、異常があればローテーションします
- API keyを絶対にログに記録しない: keyがアプリケーションのログに表示されないようにします
- HTTPSのみを使用する: 常に安全な接続でリクエストを行います