Yapılandırma değişikliği planla

POST /v1/config-plans · izin config:read ve belgedeki her türün okuma izni

Bir yapılandırma belgesini ortamın güncel yapılandırmasıyla karşılaştırır ve sonucu plan olarak saklar. Hiçbir şey değişmez: plan yalnız belgenin uygulanınca ne yapacağını gösterir. development'tan staging'e ya da production'a terfiyi uygulamadan önce incelemek için kullanın.

İstek

Alan Açıklama
document Zorunlu. GET /v1/config-export biçiminde bir yapılandırma belgesi. https://docs.keenauth.com/config/schema/v1.json JSON Schema'sına uymalıdır.
prune İsteğe bağlı, varsayılan false. true ise belgenin türlerinden belgede olmayan kaynakların silinmesi planlanır.

Yanıt

201 Created, Location: /v1/config-plans/{plan_id} ve Cache-Control: no-store ile.

Alan Açıklama
id Plan kimliği, cfgp_….
status planned; expires_at'ten sonra expired.
expires_at Plan 1 saat geçerlidir. Süresi dolduktan 7 gün sonra silinir.
summary create, update, delete ve no_op eylemlerinin sayısı.
changes Kaynak başına bir kayıt; tür sırasıyla, sonra key'e göre.
warnings secret_required: bağlantı, hedefte henüz olmayan bir istemci sırrı istiyor.

Her değişiklik kind, key, action (create, update, delete ya da no_op), object_version (hedef kaynağın plan anındaki sürümü; create'te null), requires_secret, fields ve create ile update'te istenen spec'i taşır. fields'taki her kayıt bir alan farkıdır: pointer (RFC 6901, örneğin /spec/name), op (RFC 6902'deki gibi add, remove ya da replace), before ve after. Listeler bütün değer olarak karşılaştırılır.

Dışa aktarılan bir belge değiştirilmeden verilirse, kaynakların ve küme anlamlı listelerin sırası ne olursa olsun her kaynak için no_op planlanır.

{
  "id": "cfgp_01m4qpqtywfs7930tb6kqn5rc5",
  "status": "planned",
  "prune": false,
  "kinds": ["connection"],
  "expires_at": "2026-10-12T11:00:00Z",
  "summary": {"create": 1, "update": 1, "delete": 0, "no_op": 1},
  "changes": [
    {"kind": "connection", "key": "db", "action": "no_op", "object_version": 5, "requires_secret": false, "fields": []},
    {"kind": "connection", "key": "github", "action": "create", "object_version": null, "requires_secret": true, "fields": [], "spec": {"type": "social", "strategy": "github", "name": "GitHub", "display_name": null, "status": "active", "settings": {}, "client_secret": {"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_GITHUB_CLIENT_SECRET"}}}},
    {"kind": "connection", "key": "google", "action": "update", "object_version": 4, "requires_secret": false, "fields": [{"pointer": "/spec/name", "op": "replace", "before": "Google", "after": "Google Workspace"}], "spec": {"type": "social", "strategy": "google", "name": "Google Workspace", "display_name": null, "status": "active", "settings": {}, "client_secret": {"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_GOOGLE_CLIENT_SECRET"}}}}
  ],
  "warnings": [{"code": "secret_required", "kind": "connection", "key": "github", "pointer": "/spec/client_secret"}]
}

Her plan ortamın yönetim günlüğüne bir config_plan.created kaydı yazar.

Sınırlar

Hatalar

HTTP code Ne zaman
400 malformed_request, unknown_field Gövde JSON değil ya da document ve prune dışında bir alan taşıyor.
401 unauthenticated Kimlik bilgisi eksik, geçersiz ya da iptal edilmiş.
403 insufficient_permissions Kimlik bilgisinde gerekli bir izin yok; required_permissions hepsini listeler.
413 config_document_too_large, payload_too_large Belge 5.000 kaynağı ya da 10 MiB'ı aşıyor; daha az tür planlayın.
422 validation_failed Aşağıya bakın; errors[].pointer isteğin içini gösterir (/document/...).
429 rate_limited Plan hız sınırına ya da ortamın plan kotasına ulaşıldı veya ortam aynı anda çok fazla plan hesaplıyor; Retry-After süresinden sonra yeniden deneyin (kotada en eski planın süresi dolunca ya da silinince).
503 service_unavailable Plan hesaplama kapasitesi dolu ya da bir bağımlılık geçici olarak kullanılamıyor; Retry-After süresinden sonra yeniden deneyin.
errors[].code Anlamı
required document yok.
invalid Belge bu işaretçide şemaya uymuyor.
duplicate İki kaynak aynı kind ve key'e sahip.
kind_not_listed Kaynağın türü kinds içinde değil.
secret_value Gizli bir değer bulundu; secret_ref yer tutucusu kullanın.
unresolved_reference Başvurulan key değişiklikten sonra var olmayacak.
key_in_use key, yapılandırmayla yönetilmeyen bir uygulamaya (organizasyona ait ya da kendini kaydetmiş) ya da sistem API'sine ait.
still_referenced /prune: kalan bir kaynak, planın sileceği bir kaynağa başvuruyor.
too_large Bir kaynakta, uyarıda ya da üst düzey alanda 200.000'den fazla JSON değeri var.
too_long Bağlantı settings'i 32 KiB'ı ya da uygulama jwks'i veya bir iznin consent_text_i18n'i 16 KiB'ı aşıyor.
too_deep Bağlantı settings'i 8 düzeyden derin.
reserved API identifier'ı platformun urn:idp: ad alanında.

Örnek

curl -X POST "https://api.eu.keenauth.com/v1/config-plans" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"document\": $(cat keenauth.json), \"prune\": false}"

keenauth config plan -f keenauth.yaml