Skip to main content

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キーの作成時にワークスペースを選ぶ必要はありません。現在のユーザーがアクセスできるすべてのワークスペースで、そのユーザーの権限で動作します。ユーザー識別情報を持たないサーバー間連携には、対象のワークスペースまたは組織の管理画面でシステムAPIキーを作成してください。
API keyは安全に保管し、クライアントサイドのコードに公開しないでください。API keyは サーバーサイドのアプリケーションでのみ使用してください。

API key形式

Tiro APIのkeyは次の形式に従います。
例: abc123.xR7mK9pL2qW4...
よくある間違い: Key ID(abc123)だけをBearer tokenとして使用しないでください。full keyabc123.xR7mK9pL2qW4...)、つまりkey作成時に表示された完全な文字列を使用する必要があります。

認証付きリクエストを行う

すべてのリクエストの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のみを使用する: 常に安全な接続でリクエストを行います