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やすべての権限を指定しても、ユーザーの認証情報は付与されません。
tiro auth statusで現在の認証sourceを確認してください。TIRO_TOKENは保存済みのOAuthログインより優先されます。- OAuthを使う場合は、現在のシェルから
TIRO_TOKENを削除してからtiro auth loginを実行してください。APIキーを使う場合は、TIRO_TOKENにアカウントAPIキーを設定してください。 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で取得できます。
スコープ一覧
本文の編集とリセット、および
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 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のみを使用する: 常に安全な接続でリクエストを行います