# 관리 클라이언트 생성

`POST /v1/management-clients` · 권한 `management-clients:write`

`management` 유형 애플리케이션의 관리 클라이언트 레코드를 생성합니다. 클라이언트가 사용할 수 있는 관리 API 권한과 호출할 수 있는 네트워크를 지정합니다. 레코드 ID는 애플리케이션 ID이므로, 애플리케이션당 레코드는 최대 하나입니다. 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`). 호스트 비트는 0으로 지워집니다. 생략하면 호출 키 자신의 목록이 사용됩니다. |

제한된 키는 자신이 가진 권한만 부여할 수 있고, 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`