管理クライアントの作成

POST /v1/management-clients · 権限 management-clients:write

management 種別のアプリケーションの管理クライアントのレコードを作成します。クライアントが使用できる管理 API の権限と、呼び出し元にできるネットワークを指定します。レコード ID はアプリケーション ID と同じなので、アプリケーション 1 つにつきレコードは最大 1 つです。このエンドポイントを呼び出せるのは API キーだけです。

クライアントは private_key_jwt(RFC 7523)で認証します。その公開鍵はこのリソースには含まれません。POST /v1/applications/{application_id}/credentials(type: public_key)で登録してください。ここに jwks_uri または public_keys を送ると、不明なフィールドとして拒否されます。

クライアントは環境の /oauth2/token エンドポイントからアクセストークンを取得します(client_credentials、audience = 管理 API の識別子)。そのトークンを Authorization: Bearer で送信します。トークンの有効期間は最大 10 分です。管理 API に対する権限は、トークンの scope の値のうち、このレコードにも記載されているものです。allowed_cidrs 以外からの呼び出しは 403 ip_not_allowed で失敗します。レコードまたはアプリケーションが削除された場合、あるいはアプリケーションが停止された場合、トークンは 401 で拒否されます。受け入れられるのは JWT アクセストークンのみです。

リクエスト

フィールド 型 必須 説明
application_id string はい この環境にある management 種別のアプリケーション(app_…)。
permissions string[] はい 既知の <resource>:<action> 形式の管理 API 権限を 1〜200 個(例: users:read)。重複は削除され、リストはソートされます。
allowed_cidrs string[] いいえ 最大 20 個の CIDR ブロック(例: 203.0.113.0/24)。ホストビットはクリアされます。省略すると、呼び出しキー自身のリストが使われます。

制限付きキーは自分が持つ権限しか付与できず、IP 許可リストを持つキーは自分のリスト内のネットワークしか付与できません。そうでない場合、リクエストは 403 permission_escalation で失敗します。

レスポンス

201 Created。レコードを更新または削除するときに If-Match として送る ETag ヘッダーが付きます。

{
  "application_id": "app_01h455vb4pex5vsknk084sn02q",
  "permissions": ["users:read", "users:write"],
  "allowed_cidrs": ["203.0.113.0/24"]
}

すべての書き込みは、対象(management_client とアプリケーション ID)とともに管理監査ログに記録されます。権限の値とネットワークはログに記録されません。

エラー

HTTP code 発生条件
400 unknown_field 上に記載のないフィールド(jwks_uri や public_keys など)が本文に含まれています。
403 insufficient_permissions 資格情報に management-clients:write がない、または API キーではありません。
403 permission_escalation 呼び出しキーにはこれらの権限やネットワークを付与する権限がありません。
404 not_found この環境にそのようなアプリケーションはありません。
409 conflict アプリケーションにはすでに管理クライアントのレコードがあります。
422 validation_failed フィールドがない、または不正です。未知の権限、不正な CIDR、形式の誤った application_id、または management 種別ではないアプリケーション(ポインター /application_id)。

例

curl -X POST https://api.eu.keenauth.com/v1/management-clients \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"app_01h455vb4pex5vsknk084sn02q","permissions":["users:read","users:write"],"allowed_cidrs":["203.0.113.0/24"]}'

CLI: keenauth management-clients create --application-id app_01h455vb4pex5vsknk084sn02q --permissions users:read,users:write --allowed-cidrs 203.0.113.0/24