認証
Sursa APIへのリクエストには、すべてAuthorizationヘッダーにAPIキー、またはアプリケーションのOAuthアクセストークンを付けます。
Authorization: Bearer kb_3f9c…
キーは組織を識別し、リクエストでアクセスできるもの・変更できるものを決めます。決めるのは、キーのロール、スコープ、データプロファイル、コレクションです。API専用アドレスにはセッションもCookieもありません。各リクエストは個別に認証されるので、同じキーで複数のリクエストを並行して、また複数のサーバーから送信できます。
curl https://api.sursa.com/v1/me \
-H "Authorization: Bearer $SURSA_API_KEY"以前の連携システムでは、代わりにX-API-Keyヘッダーでキーを送信している場合があります。これも引き続き受け付けますが、新しいコードではAuthorization: Bearerを使ってください。
認証情報の種類
| 認証情報 | 形式 | 使える場所 |
|---|---|---|
| 組織のAPIキー | kb_… | APIのすべてのエンドポイント。キーのロール、スコープ、データプロファイル、コレクションの範囲内。 |
| ソースキー | kbsrc_… | 自分のカスタムソースのプッシュ用エンドポイント（/v1/push/sources/{source_id}/…）だけ。 |
| OAuthアクセストークン | kbat_… | APIリファレンスにあるエンドポイント。トークンのスコープの範囲内。認可コードを使ってPOST /oauth/tokenで取得したトークンは、同意した社員の代理として動作します。client_credentialsのトークンは、APIキーと同じく組織として動作します。有効期間は1時間です。 |
いずれも同じ方法で送信します。ソースキーでは、そのソースの外にあるものを読み込んだり、検索したり、変更したりすることはできません。連携プラットフォームのように、第三者がキーを保管する場所で使ってください。
認証のエラー
| ステータスとコード | 意味 | 対処 |
|---|---|---|
401 auth.not_authenticated | キーがない、キーの入力ミス、または取り消されたキー。 | ヘッダーとキーの値を確認してください。 |
401 api_keys.expired | キーの有効期限が切れています。 | 新しいキーを作成し、古いキーと置き換えてください。 |
401 sources.push_key_invalid | ソースキーが間違っている、取り消されている、または別のソースのキーです。 | キーとパスのソースIDを確認してください。 |
401 oauth.token_expired | OAuthアクセストークンの有効期限が切れています。 | リフレッシュトークンで新しいトークンを取得してください。 |
403 api_keys.scope | キーにこの操作のスコープがありません。 | スコープを追加するか、そのスコープを持つキーを使ってください。 |
403 api_keys.feature_disabled | 組織のプランにAPIキーが含まれていません。 | 組織の管理者に連絡してください。 |
403 api_keys.ip_not_allowed | リクエストの送信元が、キーで許可されたアドレスに含まれていません。 | 許可されたネットワークから呼び出すか、キーのアドレスを変更してください。 |
403 api_keys.mcp_only | 個人用MCPキーが/mcpエンドポイント以外で使われました。 | APIには組織のAPIキーを使ってください。 |
403 oauth.operation_not_allowed | この操作は公開APIに含まれないため、OAuthトークンでは呼び出せません。 | APIリファレンスにある操作を使ってください。 |
403 org.suspended | 組織が停止されています。データは保持されています。 | 組織の管理者に連絡してください。 |
403は、リクエストは認証されたものの、許可されていないことを意味します。キーで参照できないオブジェクトには、存在しないオブジェクトと同じく404が返るので、キーのアクセス範囲の外に何があるかを知ることはできません。
データプロファイルとしての操作
adminロールのキーでは、別のグループの人たちに何が見えるかを確認できます。X-View-Asヘッダーを付けると、リクエストはデータプロファイルとして、必要に応じてロールも指定して実行されます。
curl "https://api.sursa.com/v1/cards?limit=20" \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "X-View-As: employee:viewer"このモードのリクエストは読み取りだけです。変更を行おうとすると、コードview_as.read_onlyとともに403が返ります。OAuthトークン、またはadminロールのないキーではX-View-Asを使えず、コードview_as.admin_key_requiredとともに403が返ります。存在しないプロファイルを指定したヘッダーには、コードview_as.invalid_headerとともに400が返ります。
ブラウザーアプリケーション
APIはどのWebオリジンからのリクエストも許可し（Access-Control-Allow-Origin: *）、Cookieを使わないので、ページからfetchで呼び出せます。その場合、キーはページの中にあり、ページを使う人なら誰でも見ることができます。ブラウザーからAPIを呼び出すのは、公開コレクションに限定したviewerのキーのように、それらのユーザーに見られてもかまわないキーを使う場合だけにしてください。そうでなければ、ブラウザーとSursaのあいだに自社のサーバーを置いてください。
社員にしかできないこと
組織のAPIキーは、個人ではなく組織として動作します。APIのうち2つの部分は個人に属するため、社員の代理として動作するトークンでしか使えません。つまり、Sursaのセッションか、社員の同意を得て発行されたOAuthアクセストークンです。
会話は個人のものです。組織のAPIキーでGET /v1/conversationsを呼び出すと、そのキー自身が開始した会話だけが返ります。公開APIには会話を開始する操作がないため、キーで取得するリストは通常は空で、社員の会話がキーに返されることはありません。会話を使わない質問（POST /v1/askやPOST /v1/chat）は、askスコープを持つどのキーでも使えます。社員の会話を一覧表示し、GET /v1/conversations/{conv_id}で会話の履歴を読み取るには、その社員の代理としてOAuthトークンでAPIを呼び出してください。トークンでアクセスできるのは、その社員自身の会話だけです。それ以外の会話には、コードconversations.not_foundとともに404が返ります。
カードを検証できるのは社員だけです。検証は、人が内容を確認したことを示すものです。そのため、POST /v1/cards/{card_id}/verification/verifyとPOST /v1/cards/{card_id}/verifyには、セッションか、カードを検証できる社員の代理として動作するOAuthトークンが必要です。組織のAPIキーやclient_credentialsのトークンでは、コードcards.verify_user_account_requiredとともに400が返ります。通常の確認が先に行われます。キーで参照できないカードには404が、検証を許可されていないキーには403が返ります。