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.

{
  "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

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}'