キーのスコープ
スコープは、キーで呼び出せるAPIの範囲を示します。APIリファレンスの各エンドポイントには、必要なスコープが1つ記載されています。そのスコープを持たないキーでのリクエストは、何かを読み込んだり変更したりする前に、コードapi_keys.scopeとともに403で拒否されます。
スコープが決めるのは、キーで呼び出せる操作です。それらの操作でどのオブジェクトにアクセスできるかは、引き続きキーのロール、データプロファイル、コレクションで決まります。cards:writeとviewerロールを持つキーではカードを変更できず、1つのコレクションに限定されたキーでは他のコレクションにアクセスできません。
スコープ
| スコープ | 許可される操作 |
|---|---|
cards:read | カード、コレクション、フォルダーの読み込み。 |
cards:write | カード、コレクション、フォルダーの作成・変更・削除。 |
search | ナレッジベースの検索（POST /v1/search）。 |
ask | アシスタントへの質問（POST /v1/ask、POST /v1/chat）。 |
import:write | 組織のカスタムソースへの書き込み（同期、バッチ、削除）と、その状態の読み取り。ソースとそのキーの作成にはadminが必要です。 |
webhooks:manage | Webhookの管理と、イベントフィード（GET /v1/webhook-events）の読み取り。どちらにもadminロールも必要です。 |
users:read | ユーザーとグループの読み込み。 |
users:write | ユーザーとグループの変更。 |
analytics:read | 分析データの読み込み。 |
audit:read | 監査ログの読み込み。 |
finance:read | 財務レポート、請求書、支払いの読み込み。 |
catalog:read | サービスカタログの読み込み。 |
files:read | エクスポートされた回答など、生成されたファイルの読み込み。 |
files:write | 生成されたファイルの変更と削除。 |
permissions:manage | オブジェクトに対する権限の付与と取り消し。 |
admin | 組織の設定とそのAPIキー。adminを持つキーは、他のすべてのスコープも持ちます。 |
検索と質問は、性質上は読み取りの操作です。読み取りだけを許可されたキーでも、検索と質問ができます。
スコープの選び方
連携システムが使うスコープだけを付与し、それ以外は付与しないでください。
| 連携システム | スコープ |
|---|---|
| チャットツールのQ&Aボット | search、ask |
| 自社の文書管理システムからのインポート | cards:write（カードのAPI）またはimport:write（カスタムソース） |
| データウェアハウスへのエクスポート | cards:read、users:read、イベントフィードのためのwebhooks:manage |
| 人事システムからのユーザーのプロビジョニング | users:write |
キーを作成するときにリストを渡します。
curl -X POST https://api.sursa.com/v1/api-keys \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'以前のスコープ
スコープが細分化される前に作成されたキーは、引き続き使えます。それらのスコープread、write、adminは、次のスコープの集まりを表します。
| 以前のスコープ | 意味 |
|---|---|
read | cards:read、search、ask、users:read、analytics:read、finance:read、catalog:read、files:read |
write | readのすべてに加えて、cards:write、files:write、users:write、permissions:manage |
admin | すべてのスコープ |
スコープを明示せずに作成したキーは、ロールからスコープを得ます：adminはadmin、editorとverifierはwrite、viewerはreadを得ます。
キーのスコープの確認
GET /v1/meは、どのスコープを持つキーであっても、リクエストを送信したキーのスコープを返します。スコープを明示せずに作成したキーでは、readやwriteのような、そのロールの以前のスコープが返ります。それぞれが何を表すかは上の表のとおりです。操作がapi_keys.scopeで失敗したときは、error.messageに不足しているスコープの名前が示されます。