관리 클라이언트 생성
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 헤더와 함께 반환됩니다.
{
"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