Chapter 4

API キーとサーバー間連携

人のログインを介さずに、あなたのサーバーから Cloud Auth を呼び出すための仕組みです。

権限の考え方

API キーは、発行したアカウントの権限をそのまま引き継ぎます。オーナー（USER_PRIMARY）が発行したキーで操作できるのは、自分のテナントのユーザーだけです。他のテナントのデータには一切アクセスできません。

キーで実行できない操作があります。キー自身の発行・失効、発行者のパスワード変更、発行者のアカウント削除です。漏れたキーが自らの権限を延命したり、痕跡を消したりできないようにするためです。

使い方

X-API-Key ヘッダーに発行されたシークレットを設定します。 Authorization ヘッダーや Cookie と併用する必要はありません。

curl -X POST https://api.albos.org/auth.v1.AdminService/ListUsers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ca_..." \
  -d '{"page":1,"pageSize":20}'

よく使う操作

目的	エンドポイント	備考
トークンの検証	`AuthService/VerifyToken`	受け取ったアクセストークンが今も有効か
利用者の作成	`AdminService/CreateUser`	自社サービスの登録フローから呼ぶ
利用者の一覧	`AdminService/ListUsers`	検索・絞り込み・ページングに対応
アカウントの停止	`AdminService/SetUserEnabled`	無効化すると既存セッションも直ちに無効になる
死活監視	`GET /health`	認証不要。データベースへの到達性を返す

キーの運用

用途ごとに別のキーを発行してください。失効の影響範囲を限定できます。
有効期限を設定できます。期限切れのキーは自動的に認証されなくなります。
漏えいが疑われる場合は管理画面から即座に失効させてください。失効は次のリクエストから有効です。
発行・失効はすべて操作履歴に記録されます。
1アカウントあたり有効なキーは10件までです。

認証に失敗したときの挙動

キーが無効・失効済み・期限切れの場合、また発行者のアカウントが無効化されている場合は、いずれも未認証として扱われunauthenticated が返ります。理由は区別しません。

次の章：権限とロール→