# Yönetim istemcisi oluştur

`POST /v1/management-clients` · izin `management-clients:write`

`management` türündeki bir uygulamanın yönetim istemcisi kaydını oluşturur: istemcinin kullanabileceği yönetim API izinleri ve çağrı yapabileceği ağlar. Kaydın kimliği uygulamanın kimliğidir; bir uygulamanın en çok bir kaydı olur. Bu ucu yalnız API anahtarı çağırabilir.

İstemci `private_key_jwt` (RFC 7523) ile kimlik doğrular. Ortak anahtarları bu kaynakta yoktur: onları `POST /v1/applications/{application_id}/credentials` (`type: public_key`) ile kaydedin. Burada `jwks_uri` ya da `public_keys` göndermek bilinmeyen alan olarak reddedilir.

İstemci erişim token'ını ortamının `/oauth2/token` ucundan alır (`client_credentials`, `audience` = yönetim API'sinin tanımlayıcısı) ve `Authorization: Bearer` olarak gönderir. Token en çok 10 dakika geçerlidir. Yönetim API'sindeki izinleri, token'ın `scope` değerlerinden bu kayıtta da yazılı olanlardır; `allowed_cidrs` dışından gelen çağrı `403 ip_not_allowed` alır. Kayıt ya da uygulama silinirse ya da uygulama askıya alınırsa token `401` ile reddedilir. Yalnız JWT erişim token'ları kabul edilir.

## İstek

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `application_id` | string | evet | Bu ortamdaki `management` türünde bir uygulama (`app_…`). |
| `permissions` | string[] | evet | 1-200 bilinen `<kaynak>:<eylem>` yönetim API izni, örneğin `users:read`. Tekrarlar atılır, liste sıralanır. |
| `allowed_cidrs` | string[] | hayır | En çok 20 CIDR bloğu, örneğin `203.0.113.0/24`. Konak bitleri temizlenir. Verilmezse çağıran anahtarın kendi listesi kullanılır. |

Kısıtlı anahtar yalnız kendi taşıdığı izinleri, IP izin listesi olan anahtar yalnız kendi ağlarının içindeki ağları verebilir; aksi `403 permission_escalation`.

## Yanıt

`201 Created`; kaydı güncellemek ya da silmek için `If-Match` olarak göndereceğiniz `ETag` başlığıyla.

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

Her yazma yönetim audit kaydına hedefle (`management_client` ve uygulama kimliği) girer; izin değerleri ve ağlar kayda yazılmaz.

## Hatalar

| HTTP | code | Ne zaman |
|---|---|---|
| 400 | `unknown_field` | Gövdede yukarıda olmayan bir alan var, örneğin `jwks_uri` ya da `public_keys`. |
| 403 | `insufficient_permissions` | Kimlik bilgisinde `management-clients:write` yok ya da kimlik bilgisi API anahtarı değil. |
| 403 | `permission_escalation` | Çağıran anahtar bu izinleri ya da ağları veremez. |
| 404 | `not_found` | Bu ortamda böyle bir uygulama yok. |
| 409 | `conflict` | Uygulamanın zaten bir yönetim istemcisi kaydı var. |
| 422 | `validation_failed` | Bir alan eksik ya da geçersiz: bilinmeyen izin, geçersiz CIDR, bozuk `application_id` ya da türü `management` olmayan uygulama (işaretçi `/application_id`). |

## Örnek

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