APIキーとスコープ

Sursa APIへのリクエストは、すべて組織のAPIキーで行います。キーは個人ではなく組織に属します。キーを作成した社員が退職してもキーは動き続け、キーでできることはキー自体に設定されます。

キーでできること

キーの3つの設定が、そのキーを使ったリクエストでアクセスできるもの・変更できるものを決めます。どの設定も、他の設定の範囲を狭めるだけです。

設定	制御する内容
ロール（Role）	`admin`、`editor`、`verifier`、`viewer`のいずれか。ユーザーと同じロールです。キーは、そのロールのユーザーができることを行えます。
スコープ（Scopes）	キーで呼び出せるAPIの範囲。たとえば`cards:read`や`webhooks:manage`です。キーのスコープを参照してください。
データプロファイル	省略可能。そのプロファイルを持つユーザーと同じように、プロファイルで許可されたナレッジのカテゴリにキーを限定します。

キーは、一部のコレクションに限定したり、有効期限を設定したりすることもできます。これらの範囲外のリクエストは失敗します。スコープが不足していればコードapi_keys.scopeとともに403が返り、キーで参照できないオブジェクトには、存在しない場合とまったく同じく404が返ります。

連携システムごとに専用のキーを用意し、必要最小限のロールとスコープを付与してください。ドキュメントを書き込むだけの同期ジョブにadminは不要で、レポート用のジョブに書き込みのスコープは不要です。

キーを作成する

組織の管理者は、SursaのAdministration → API keys（管理 → APIキー）でキーを作成します。または、adminロールを持つキーかセッションを使って、POST /v1/api-keysで作成します。

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

レスポンスのkeyにキーの値が含まれます。この値は一度だけ表示されます。Sursaはそのハッシュだけを保存するので、もう一度表示することはできません。キーはkb_に43文字が続く形式です。先頭の数文字（prefix）はキーの一覧に表示されるので、キーを見分けるのに使えます。

scopesを指定しないと、キーにはロールのスコープが付与されます。さらに狭めるにはscopesを渡してください。expires_atを指定しないと、キーに有効期限はありません。

キーを秘密に保つ

キーはシークレットマネージャーかサービスの環境変数に保存し、ソースコードには決して書かないでください。
キーは自社のサーバーからだけ使ってください。Sursaはブラウザーからのリクエストも受け付けますが（CORSは開放されています）、Webページの中のキーは、そのページを開いた全員に見えます。
キーを決してURLに含めて送信しないでください。キーはAuthorizationヘッダーでだけ送信します。
キーが漏えいしたら、すぐに取り消して新しいキーを作成してください。

キーを確認する

GET /v1/meは、キー、そのロール、有効なスコープ、データプロファイル、有効期限、レート制限を返します。どのスコープを持つキーでも、有効なキーであれば動作するので、連携システムの接続テストや、403を調査するときに使ってください。

キーをローテーションする

ローテーションでは、連携システムを止めずにキーを置き換えます。最も手早い方法は、キーを再発行することです。POST /v1/api-keys/{key_id}/rollは、同じキーに新しい値を発行します。ロール、スコープ、コレクション、有効期限はそのままです。以前の値はoverlap_hoursのあいだ（デフォルトは24時間、最大168時間）引き続き使えるので、そのあいだに新しい値をデプロイできます。POST /v1/api-keys/{key_id}/revoke-previousを呼び出すと、並行期間を早めに終了できます。

別のキーに置き換える場合は、次の手順で行います。

同じロール、スコープ、データプロファイルで新しいキーを作成します。
新しいキーを連携システムにデプロイします。
古いキーが使われなくなるまで、Administration → API keys（またはGET /v1/api-keysのlast_used）で確認します。
古いキーを取り消します。

キーには有効期限を設定し、期限の前にローテーションしてください。Sursaは、キーの期限が切れる前に組織の管理者に通知します。期限切れのキーには、コードapi_keys.expiredとともに401が返ります。

キーを取り消す

キーは、Administration → API keysまたはDELETE /v1/api-keys/{key_id}で取り消します。取り消しは、数秒以内にすべてのAPIサーバーで有効になります。取り消されたキーでのリクエストには、コードauth.not_authenticatedとともに401が返ります。

カスタムソースのキー

カスタムソースには専用の種類のキーがあります。このキーはkbsrc_で始まり、その1つのソースにドキュメントを書き込むことしかできず、何かを読み込んだり検索したりすることはできません。Zapierのような連携プラットフォームに渡すキーとして、最も安全です。ソースのページのAPI keys（APIキー）で作成するか、POST /v1/sources/{source_id}/push-keysで作成します。

キーを使えないとき

APIキーは組織のプランに含まれる機能です。プランに含まれていない場合、キーの作成と、キーを使ったすべてのリクエストに、コードapi_keys.feature_disabledとともに403が返ります。