# API anahtarı oluşturma

`POST /v1/api-keys` · İzin `api-keys:write` · zorunlu `Idempotency-Key`

Ortam için bir yönetim API anahtarı oluşturur. Bir `secret` anahtarı tüm yönetim API'sine erişir; bir `restricted` anahtarı yalnızca listelenen izinleri taşır (`<resource>:<action>`).

- **Ham anahtar.** Yanıt `key` değerini yalnızca bir kez içerir (`idp_sk_live_…`, `idp_sk_test_…`, `idp_rk_live_…` veya `idp_rk_test_…`). Bu değer bir daha alınamaz; hemen saklayın. Yanıtta `Cache-Control: no-store` bulunur.
- **Yetki yükseltme yok.** Bir anahtar, kendi izinlerini aşan izinlere sahip bir anahtar oluşturamaz ve `restricted` bir anahtar `secret` anahtar oluşturamaz. Yeni anahtar, çağıran anahtarın sona ermesinden sonra sona eremez; `allowed_cidrs` içeren çağıran bir anahtar yalnızca kendi ağları içindeki ağlarla sınırlı anahtarlar oluşturabilir. `allowed_cidrs` atlanırsa yeni anahtar çağıran anahtarın listesini alır (`permission_escalation`).
- **Sınırlar.** Ortam başına en fazla 50 etkin anahtar, anahtar başına en fazla 20 CIDR bloğu ve en fazla 730 gün sonrasına kadar son kullanma tarihi. `allowed_cidrs` içeren bir anahtar yalnızca bu ağlardan kabul edilir.
- **Idempotent tekrar.** İsteğin aynı `Idempotency-Key` ile tekrarlanması, saklanan yanıtı anahtar olmadan yeniden oynatır: gövdede `secret_redacted: true` bulunur ve `key` yoktur. Anahtar kaybolduysa yeni bir anahtar oluşturun.

## İstek

Gövde:

| Alan | Tür | Açıklama |
|---|---|---|
| `name` | string | Zorunlu. 1–100 karakter. |
| `type` | string | Zorunlu. `secret` veya `restricted`. |
| `permissions` | string[] | `restricted` için zorunlu ve boş olamaz (en fazla 200); `secret` için yoksa veya boş olmalıdır. Çağıranın kendi izinlerini aşamaz. |
| `expires_at` | string (date-time) | Zorunlu, gelecekte olmalı ve en fazla 730 gün sonra olabilir. |
| `allowed_cidrs` | string[] | İsteğe bağlı, en fazla 20 CIDR bloğu. |

## Yanıt

`Cache-Control: no-store` ile `201 Created`. Liste yanıtındaki gibi anahtar nesnesi, ayrıca `key`.

```json
{
  "id": "key_0000000000000000000000001z",
  "name": "ci",
  "type": "restricted",
  "permissions": ["users:read"],
  "allowed_cidrs": [],
  "last4": "xxxx",
  "created_by": "key_…",
  "created_at": "2026-10-01T10:00:00Z",
  "expires_at": "2027-10-01T10:00:00Z",
  "last_used_at": null,
  "last_used_ip": null,
  "rotated_from": null,
  "revoked_at": null,
  "revoke_reason": null,
  "key": "<shown once>"
}
```

## Hatalar

| HTTP | `code` | Ne zaman |
|---|---|---|
| 401 | `unauthenticated` | Anahtar eksik, geçersiz veya iptal edilmiş. |
| 403 | `insufficient_permissions` | Anahtarın gerekli izni yok. |
| 403 | `permission_escalation` | İstek, anahtara çağıran anahtarın sahip olduğundan daha fazla izin, daha geniş bir ağ aralığı veya daha ileri bir son kullanma tarihi verecekse; `restricted` bir anahtar kendi izinlerinin ötesinde bir anahtarı oluşturmaya, döndürmeye veya iptal etmeye çalışırsa; ya da başka bir anahtar, panelde oluşturulmuş bir anahtarı döndürmeye veya iptal etmeye çalışırsa. |
| 409 | `api_key_limit_reached` | Ortamda zaten en fazla 50 etkin anahtar var. |
| 422 | `validation_failed` | Gövde geçersiz: `name` eksik veya çok uzun, bilinmeyen `type`, `permissions` olmadan `restricted`, `permissions` ile `secret`, hatalı izin veya CIDR, geçmişte olan ya da 730 günden fazla ileri bir `expires_at`. |

## Örnek

```bash
curl -X POST https://api.eu.keenauth.com/v1/api-keys \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci","type":"restricted","permissions":["users:read"],"expires_at":"2027-10-01T10:00:00Z"}'
```