# 管理クライアントの作成

`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` ヘッダーが付きます。

```json
{
  "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`)。 |

## 例

```bash
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`