APIキー
Tiro API は API キーで認証します。すべてのリクエストのAuthorization ヘッダーに、API キーを Bearer トークンとして送信してください。
アカウントのAPIキーはユーザーアカウントに紐づき、そのユーザーが現在アクセスできるすべてのワークスペースで、ユーザー本人の権限で動作します。ワークスペース・組織のAPIキーは、それぞれ紐づくワークスペースまたは組織を基準に動作します。
メンバーが個別にキーを発行せず、一度の同意で社内システムを連携したい場合は、API KeyではなくOAuthアプリをご利用ください。登録とトークン発行の流れはOAuthアプリ連携にまとめています。
キーの種類と権限
Tiro API keyは、リクエストの主体によって3種類に分かれます。
ワークスペースのAPIキーと組織のAPIキーはどちらもユーザーを介さずに動作するため、この2つをまとめてシステムAPIキーと呼びます。このドキュメントでシステムAPIキーと書いている場合は、両方を指します。
ワークスペースのAPIキーは、ワークスペースの全メンバーに共有されたフォルダに入っているノートのみを扱います。タイトルの変更、共有リンクの作成、ドキュメントの生成など、ノートを変更するリクエストにも同じ範囲が適用されます。個人フォルダにあるノート、一部のメンバーにだけ共有したフォルダのノート、どのフォルダにも入れていないノートは、この範囲から外れます。それらのノートも扱う必要がある場合は、アカウントのAPIキーを作成して使用してください。
移行期間について。 この読み取り範囲が適用される前に作成されたワークスペースのAPIキーは、当面これまでの動作を維持し、順次移行される予定です。そのため、新しく作成したキーが以前のキーより少ないノートを返すことがありますが、これは正常な動作です。キーの種類ごとの範囲と、範囲の外にあるノートがどのようなレスポンスになるかは、システムAPIキーが読み取るノートの範囲にまとめています。
ワークスペースのAPIキーがまだワークスペースに紐づいていない場合、認証は
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
ログイン
platform.tiro.ooo/me/api-keysにアクセスします。
2
アカウントのAPIキーを作成
Create New API Key をクリックし、名前を付けてから、ドットを含むfull keyをコピーします —
abc123.xR7mK9pL2qW4...。3
保存
環境変数として保存します。secretは一度だけ表示され、ダイアログを閉じると復元できません。
API key形式
Tiro APIのkeyは次の形式に従います。abc123.xR7mK9pL2qW4...
認証付きリクエストを行う
すべてのリクエストのAuthorizationヘッダーにAPI keyを含めます。
認証エラー
認証に失敗すると、401 Unauthorizedレスポンスが返されます。
- Authorizationヘッダーがない
- keyの形式が不正(
{id}.{secret}である必要があります) - 不明なkey id
- 無効、期限切れ、または削除されたkey
セキュリティのベストプラクティス
環境変数
環境変数を使用して、API keyを安全に保管します。その他のセキュリティガイドライン
- keyを定期的にローテーションする: 使用していないkeyを削除し、新しいkeyを生成します
- 環境ごとにkeyを分ける: 開発環境と本番環境で異なるkeyを使用します
- 利用状況を監視する: API keyの利用状況を追跡し、異常があればローテーションします
- API keyを絶対にログに記録しない: keyがアプリケーションのログに表示されないようにします
- HTTPSのみを使用する: 常に安全な接続でリクエストを行います