# İmzalama anahtarlarını yenileme

`POST /v1/signing-keys:rotate` · izin `signing-keys:write`

Otomatik takvimin dışında, hemen bir imzalama anahtarı yenilemesi çalıştırır.

- `mode: immediate`: Normal yenileme adımı hemen çalışır. Önceden yayımlanmış `next` anahtarı imzalamaya başlar, eski `active` anahtarı 7 gün boyunca `retired` olarak kalır ve yeni bir `next` anahtarı yayımlanır. `next`, etkin anahtardan farklı bir algoritma kullanıyorsa (algoritma değişikliği) ve 7 günden kısa süre önce yayımlanmışsa, çağrı `409 next_key_too_young` hatasıyla başarısız olur.
- `mode: emergency` (anahtarın ele geçirildiğinden şüphelenilmesi): Eski `active` anahtarı iptal edilir ve JWKS'ten **hemen** çıkarılır; `next` etkin hale gelir ve yeni bir `next` üretilir. `revoke_next: true` ayrıca `next` anahtarını iptal eder ve yeni üretilmiş, hiç yayımlanmamış bir anahtarı etkinleştirir. `revoke_sessions: true` ayrıca ortamın tüm oturumlarını ve yenileme jetonu ailelerini iptal eder, böylece kullanıcılar yeniden giriş yapmak zorunda kalır. `reason` zorunludur.

## Federasyon anahtarları

`use` ortamın federasyon anahtarlarından birini de belirtebilir: `saml_sp_signing` ve `saml_sp_encryption` (SP metadata'nızda yayımlanan SAML hizmet sağlayıcı imzalama ve şifreleme anahtarları) veya `oidc_rp_signing` (kurumsal OIDC bağlantılarının `private_key_jwt` anahtarı, `/sso/jwks.json` adresinde yayımlanır). Bu anahtarlar her zaman RSA-3072'dir ve kendiliğinden yılda bir kez yenilenir: yeni bir `next` anahtarı, devralmasından 30 gün önce yayımlanır ve eski anahtar devralmanın ardından 30 gün boyunca yayımlı kalır.

- `mode: immediate`, önceden yayımlanmış `next` anahtarını hemen etkinleştirir; eski anahtar 30 gün daha yayımlı kalır (`retired_kids` içinde görünür). Yayımlanmış bir `next` anahtarı yoksa çağrı `409 conflict` hatasıyla başarısız olur; `next` anahtarı 7 günden kısa süre önce yayımlanmışsa `409 next_key_too_young` hatasıyla başarısız olur.
- `mode: emergency`, etkin anahtarı metadata'dan veya JWKS'ten **hemen** kaldırır ve özel anahtarını yok eder (`revoked_kids`). Yayımlanmış `next` anahtarı etkin hale gelir; böyle bir anahtar yoksa veya `revoke_next: true` ile kullanılıyorsa, hiç yayımlanmamış yeni bir anahtar bu görevi üstlenir. Metadata'yı veya JWKS'i URL'sinden yükleyen kimlik sağlayıcılar değişikliği bir sonraki yenilemelerinde alır. Metadata'yı veya sertifikayı elle yüklediğiniz sağlayıcılar, yeni sertifikayı yükleyene kadar oturum açmaları reddeder; bu durum için etkilenen her bağlantı için bir `connection.sp_certificate_rotation_started` webhook olayı gönderilir.

Federasyon anahtarı için yanıttaki `next_kid` `null` değerini alır, `removed_kids` boş kalır ve `revoke_sessions` kullanılamaz. Ortam hiç SAML veya `private_key_jwt` kullanmadıysa yenilenecek anahtar yoktur ve çağrı `409 conflict` hatasıyla başarısız olur.

### Bağlantı anahtarları

Bir SAML bağlantısı, ortamın anahtarları yerine kendine özgü SP anahtarlarına sahip olabilir. Bunları yenilemek için `connection_id` (`conn_…`) değerini `use: saml_sp_signing` veya `saml_sp_encryption` ile ekleyin. Aynı modlar, izinler ve kurallar geçerlidir; ancak yalnızca o bağlantının anahtar kümesi değişir: ortamın anahtarları ve diğer bağlantıların anahtarları olduğu gibi kalır ve `connection.sp_certificate_rotation_started` olayı yalnızca o bağlantı için gönderilir. Denetim kaydı, hedef olarak ortamı, bağlantıyı ise `metadata.connection_id` alanında belirtir. Bilinmeyen bir bağlantı veya başka bir ortama ait bir bağlantı `404 not_found` hatasıyla başarısız olur; ortamın anahtarlarını kullanan bir bağlantı `409 connection_keys_not_dedicated` hatasıyla başarısız olur (ortamın anahtarlarını `connection_id` olmadan yenileyin). `connection_id` belirtilmezse ortamın anahtar kümesi yenilenir.

Acil durum modu, `signing-keys:write` dışında, kimlik bilgisinde açıkça verilmiş `signing-keys:emergency` iznini gerektirir: bu çağrıyı yalnızca kısıtlı bir anahtar veya bu izni taşıyan bir M2M istemcisi yapabilir. Tam erişimli bir gizli anahtar (`idp_sk_…`) acil durum modunda `403 insufficient_permissions` alır.

Yeni jeton imzalama anahtarları, ortam politikasının algoritmasını kullanır ([politikayı alın](/docs/api/management/signing-keys/get-policy)). Başarılı bir jeton imzalama anahtarı yenilemesi `signing_key.rotated` veya `signing_key.revoked` webhook olayını yayar; her yenileme bir yönetim denetim kaydı yazar. Bu uç nokta "anahtar ve gizli anahtar düzenleme" hız sınırı ailesine aittir. Bir `Idempotency-Key` başlığı gönderin: ağ hatasından sonra yapılan yeniden denemede, iki kez yenilemek yerine ilk sonuç döndürülür.

## İstek

JSON gövdesi (bilinmeyen alanlar `400 unknown_field` ile reddedilir):

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `Idempotency-Key` | başlık | hayır | Önerilir. `A-Z a-z 0-9 _ -` karakterlerinden 16-64 karakter. |
| `mode` | metin | evet | `immediate` veya `emergency`. |
| `use` | metin | hayır | Yenilenecek anahtar. Varsayılan `token_signing` (erişim ve ID jetonu imzalama anahtarı). Federasyon anahtarları `saml_sp_signing`, `saml_sp_encryption` ve `oidc_rp_signing`'tir (bkz. [Federasyon anahtarları](#federasyon-anahtarları)). |
| `revoke_sessions` | boolean | hayır | Yalnızca acil durum ve `token_signing` için. Ayrıca tüm oturumları ve yenileme jetonlarını iptal eder. Varsayılan `false`. |
| `revoke_next` | boolean | hayır | Yalnızca acil durum için. Ayrıca yayımlanmış `next` anahtarını iptal eder. Varsayılan `false`. |
| `reason` | metin | acil durumda: evet | Yalnızca acil durum için. 1-512 yazdırılabilir ASCII karakteri, örneğin bir olay numarası. Buraya gizli bilgi veya kişisel veri yazmayın. |
| `connection_id` | metin | hayır | Yalnızca `saml_sp_signing` ve `saml_sp_encryption` için. Kendine özgü SP anahtarları olan bir SAML bağlantısı (`conn_…`); ortamın yerine bu bağlantının anahtar kümesi yenilenir (bkz. [Bağlantı anahtarları](#bağlantı-anahtarları)). |

`mode: immediate` ile `revoke_sessions: true`, `revoke_next: true` veya bir `reason` göndermek `422` hatasıyla başarısız olur (`not_allowed`). `token_signing` veya `oidc_rp_signing` ile birlikte bir `connection_id` de aynı şekilde başarısız olur.

## Yanıt

`200 OK`, yenilemenin sonucunu içerir. `activated_kid`, bundan sonra imzalayan anahtardır; `next_kid` ise yeni yayımlanan `next` anahtarıdır (federasyon anahtarı için `null`). `retired_kids`, imzalamayı bırakmış ve yayımlı kalmaya devam eden anahtarlardır (jeton imzalama anahtarı için 7 gün, federasyon anahtarı için 30 gün); `revoked_kids`, acil durum yenilemesiyle JWKS'ten kaldırılan anahtarlardır; `removed_kids` ise 7 günlük süresi dolmuş ve aynı adımda JWKS'ten çıkmış emekli anahtarlardır.

```json
{
  "mode": "immediate",
  "use": "token_signing",
  "activated_kid": "ypeBEsobvcr6wjGzmiPcTaeG7_gUfE5yuYB3ha_uSLs",
  "next_kid": "GKw-c0PwFokMUQ6T-TUmEWnZ4_VlQ2Qpgw-vCTT0-OQ",
  "retired_kids": ["PiPoFgA5WUoziU9lZOGxNIu9egCI1CxKy3PurtWcAJ0"],
  "revoked_kids": [],
  "removed_kids": ["Ln0sA6lQeuJl7PW1NWiFpTOTogKdJBOUmXJloaJa78Y"],
  "revoke_sessions": false
}
```

## Hatalar

| HTTP | kod | Ne zaman |
|---|---|---|
| 400 | `unknown_field` | Gövde bilinmeyen bir alan içeriyor. |
| 400 | `malformed_request` | Gövde geçerli bir JSON değil veya `Idempotency-Key` başlığı hatalı ya da tekrarlanmış. |
| 403 | `insufficient_permissions` | Kimlik bilgisi `signing-keys:write` iznine sahip değil veya acil durum modu, açıkça verilmiş `signing-keys:emergency` olmadan istendi. |
| 404 | `not_found` | `connection_id` bu ortama ait hiçbir SAML bağlantısını belirtmiyor. |
| 409 | `connection_keys_not_dedicated` | `connection_id`, ortamın SP anahtarlarını kullanan bir bağlantıyı belirtiyor. |
| 409 | `next_key_too_young` | Bir algoritma değişikliği bekliyor ve `next` anahtarı 7 günden kısa süre önce yayımlanmış veya (federasyon anahtarı, `immediate`) `next` anahtarı 7 günden kısa süre önce yayımlanmış. |
| 409 | `conflict` | Ortamın yayımlanmış bir `next` anahtarı yok, federasyon `use` için etkin bir anahtarı yok veya önceki federasyon anahtarı hâlâ 30 günlük geçiş süresinde. |
| 415 | `unsupported_media_type` | İçerik türü `application/json` değil. |
| 422 | `validation_failed` | Bir alan eksik veya geçersiz; işaretçi alanı belirtir, örneğin `/reason`. |
| 422 | `idempotency_key_reuse` | `Idempotency-Key` daha önce farklı bir gövdeyle kullanılmış. |
| 501 | `not_implemented` | İşlem bu dağıtımda henüz kullanılamıyor. |
| 401 | `unauthenticated` | Kimlik bilgisi eksik, geçersiz veya iptal edilmiş. |
| 429 | `rate_limited` | Hız sınırı aşıldı; `Retry-After` süresinin ardından yeniden deneyin. |
| 503 | `service_unavailable` | Bir bağımlılık geçici olarak kullanılamıyor; `Retry-After` süresinin ardından yeniden deneyin. |

## Örnek

Normal yenileme:

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

`signing-keys:write` ve `signing-keys:emergency` iznini veren kısıtlı bir anahtarla acil durum yenilemesi:

```bash
curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","revoke_sessions":true,"reason":"INC-2041 key exposure"}'
```

Yayımlanmış `next` anahtarını da iptal eden, SAML SP imzalama anahtarının acil durum yenilemesi:

```bash
curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","use":"saml_sp_signing","revoke_next":true,"reason":"INC-2042 SP key exposure"}'
```

Bir bağlantının kendine özgü SAML SP imzalama anahtarının acil durum yenilemesi:

```bash
curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","use":"saml_sp_signing","connection_id":"conn_01h2xcejqtf2nbrexx3vqjhp41","reason":"INC-2043 connection key exposure"}'
```