# API anahtarını döndürme

`POST /v1/api-keys/{key_id}:rotate` · izin `api-keys:write` · isteğe bağlı `Idempotency-Key`

Bir anahtarı döndürür: aynı ad, tür, izinler ve `allowed_cidrs` ile YENİ bir anahtar oluşturur ve bunu döndürür. Eski anahtar `overlap_hours` süresince geçerli kalır, ardından çalışmayı durdurur.

- **Yeni anahtar.** Yanıt yeni anahtarı açıklar; `rotated_from` eski anahtarın kimliğidir ve `key` ham anahtarı yalnızca bir kez taşır (`Cache-Control: no-store`). Bunu dağıtın, ardından eski anahtarın süresinin dolmasına izin verin.
- **Örtüşme.** Eski anahtar gelecekteki bir `revoked_at` değeri ve `revoke_reason: rotated` alır; `overlap_hours: 0` ile anında iptal edilir.
- **Yetki yükseltme yok.** Bir anahtar, izinleri kendi izinlerini aşan bir anahtarı döndüremez; `restricted` bir anahtar `secret` bir anahtarı döndüremez. Yeni anahtarın son kullanma tarihi, bir anahtar kendini döndürse bile çağıran anahtarın son kullanma tarihinden sonra olamaz (ömrü panelden uzatın). `allowed_cidrs` içeren bir çağıran anahtar yalnızca kendi ağları içindeki ağlarla sınırlı anahtarları döndürebilir. Panelde oluşturulan bir anahtar ve ondan döndürülen her anahtar yalnızca kendisi veya panel tarafından döndürülebilir (`permission_escalation`). Yeni anahtar, eski anahtarın `created_by` değerini korur; döndüren anahtar denetim günlüğüne kaydedilir.
- **İdempotent tekrar.** Aynı `Idempotency-Key` ile yapılan bir tekrar `key` alanını içermez ve `secret_redacted: true` döndürür.

## İstek

| Parametre | Konum | Açıklama |
|---|---|---|
| `key_id` | yol | API anahtarı kimliği (`key_…`). |

Gövde:

Gövde isteğe bağlıdır; gönderilmezse tüm varsayılanlar uygulanır.

| Alan | Tür | Açıklama |
|---|---|---|
| `overlap_hours` | tam sayı | İsteğe bağlı, 0–168, varsayılan 24. Eski anahtarın kaç saat geçerli kalacağı. |
| `expires_at` | string (date-time) | İsteğe bağlı. YENİ anahtarın son kullanma tarihi; varsayılan şimdi + 365 gün, en fazla çağıran anahtarın son kullanma tarihi ve en fazla 730 gün. |

## Yanıt

`Cache-Control: no-store` ile `200 OK`. YENİ anahtar nesnesi ve `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": "key_…",
  "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, bir anahtara çağıran anahtardan daha fazla izin, daha geniş bir ağ aralığı veya daha ileri bir son kullanma tarihi verecekse; `restricted` bir anahtar kendi izinlerinin ötesinde 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. |
| 404 | `not_found` | Anahtar bu ortamda yok. |
| 409 | `conflict` | Anahtar zaten iptal edilmiş, süresi dolmuş veya zaten döndürülmüş (etkin değil). |
| 409 | `api_key_limit_reached` | Ortamda zaten en fazla 50 etkin anahtar var. |
| 422 | `validation_failed` | Gövde geçersiz: `overlap_hours` 0–168 aralığının dışında veya `expires_at` geçmişte ya da 730 günden fazla ileride. |

## Örnek

```bash
curl -X POST "https://api.eu.keenauth.com/v1/api-keys/key_0000000000000000000000001z:rotate" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"overlap_hours":24}'
```