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が続く場合は、キーが接続されているワークスペースと作成画面を先に確認してください。

CLIでフォルダを取得する場合

tiro folders listとtiro folders treeには、OAuthログインまたはアカウントAPIキーが必要です。連携先で求められる「個人キー」は、このアカウントAPIキーです。ワークスペース・組織のシステムキーにfolder:readやすべての権限を指定しても、ユーザーの認証情報は付与されません。
  1. tiro auth statusで現在の認証sourceを確認してください。TIRO_TOKENは保存済みのOAuthログインより優先されます。
  2. OAuthを使う場合は、現在のシェルからTIRO_TOKENを削除してからtiro auth loginを実行してください。APIキーを使う場合は、TIRO_TOKENにアカウントAPIキーを設定してください。
  3. tiro wiki workspacesで対象GUIDを確認し、tiro folders list --workspace <guid>またはtiro folders tree --workspace <guid>を実行してください。
403のinsufficient_scopeは、必要な操作権限が不足していることを示します。OAuthでは再ログインしてfolder:readを含む権限に同意し、APIキーでは権限を変更するかキーを交換してください。folder:writeもfolder:readを含みます。CLIのOAuth URLではscopeを省略しますが、サーバーがアプリとリソースの許可範囲を計算して同意画面を表示するため、URLに手動で追加する必要はありません。 401とUser API key is required for folder accessが返る場合、その操作にはユーザー認証が必要です。アカウントAPIキーまたはOAuthに切り替えてください。スコープを増やしても解決しません。ノートが0件の場合は、システムAPIキーで取得できるノートの範囲を確認してください。

スコープ (Scope)

スコープはキーが実行できる操作を制限します。キーの発行時に選択し、後から変更もできます。
  • スコープを指定しないキーは、アクセス可能なリソースの範囲内で、今後追加される API を含むすべての操作を行えます。 最小権限が必要な場合は、キーに必要なスコープを明示してください。スコープは権限を付与するのではなく絞り込むためのもので、指定したスコープに対応する API のみ呼び出せます。それ以外は 403 insufficient_scope で拒否されます。
  • write スコープは同じリソースの read を含みます。 発行済みのキーにも同じルールが適用されます。
  • スコープはすべてのキー種別(ユーザー・ワークスペース・組織)に適用されます。
  • 選択可能なスコープ一覧は GET /v1/api-key-scopes で取得できます。
内容の編集・リセット API と MCP ツールは現在 dev 環境で QA 中であり、本番環境では利用できません。スコープがあっても、無効化されている API は利用できません。

スコープ一覧

本文の編集とリセット、および note_summary:write は現在 dev 環境で検証中です。本番環境ではまだ利用できません。write 権限を付与しても、対象環境で無効な機能は有効になりません。

API ごとに必要なスコープ

スコープを指定したキーは、そのスコープを持つ API のみ呼び出せます。スコープを指定しなくても、キー種別とリソースへのアクセス権限による制限は維持されます。

dev 環境の本文編集とリセット API

本文の編集とリセット、および note_summary:write は現在 dev 環境で検証中です。本番環境ではまだ利用できません。write 権限を付与しても、対象環境で無効な機能は有効になりません。 取得レスポンスの editState.etag を、そのまま復元リクエストの etag に指定します。undoAvailable と canReset は、その認証情報と現在の内容で実行できる操作を示します。409 の場合は再取得し、変更内容を確認してから復元を選び直してください。新しい etag で Undo を自動再試行しないでください。 段落の Undo は、指定した段落・フィールドの保存1回分を取り消します。transcript、translated、diarized-transcript、summary に対応します。段落の要約は、復元可能な履歴が記録される新しい保存から Undo が可能です。以前の保存は取り消せません。 editState.canResetByKind は original、translated、summary の全段落リセットの可否を示します。各段落に含まれますが、ノート内のすべての段落が対象です。 POST /v1/external/notes/{noteGuid}/paragraphs:reset に { "kind": "original", "etag": "取得した値" } を送信します。kind は original、translated、summary のいずれかです。すべての段落で選択した種類を一度にリセットします。original は通常の原文と話者別の原文・話者の割り当てをまとめてリセットし、翻訳と段落の要約は保持します。translated は翻訳のみ、summary は段落の要約のみをリセットします。対象の内容の以前の Undo 履歴を終了し、他の内容とその Undo 履歴を保持します。原文のリセットは、影響を受ける以前の話者変更の Undo も無効にします。対象の内容を1つでもリセットできない場合、部分的に変更せずリクエスト全体が失敗します。 既存の段落単位のリセットは動作を維持します。その段落の原文・翻訳・話者別の文章・話者の割り当てを生成時の状態に戻し、段落の要約は保持します。話者の Undo は文章の編集を保持します。ノート要約・文書の Undo は、それぞれの最新の保存を1回ずつ取り消します。リセットは要約または文書全体を生成内容に戻し、それ以前の Undo 履歴を終了します。文書のセクション単位のリセットは提供していません。 既存の編集・復元 API の expectedRevision 契約は維持されます。上記のその他の復元パスには { "etag": "取得した値" } を指定して POST します。成功時は更新された復元状態が返るため、本文を再取得してください。

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