Eine Konfigurationsänderung planen

POST /v1/config-plans · Berechtigung config:read und die Leseberechtigung jedes Typs im Dokument

Vergleicht ein Konfigurationsdokument mit der aktuellen Konfiguration der Umgebung und speichert das Ergebnis als Plan. Es wird nichts geändert: Ein Plan zeigt nur, was das Anwenden des Dokuments bewirken würde. Prüfen Sie damit eine Übernahme von development nach staging oder production, bevor Sie sie anwenden.

Anfrage

Feld Beschreibung
document Erforderlich. Ein Konfigurationsdokument im Format von GET /v1/config-export. Es muss dem JSON Schema https://docs.keenauth.com/config/schema/v1.json entsprechen.
prune Optional, Standard false. Bei true wird das Löschen von Ressourcen der Dokumenttypen geplant, die im Dokument fehlen.

Antwort

201 Created mit Location: /v1/config-plans/{plan_id} und Cache-Control: no-store.

Feld Beschreibung
id Plan-ID, cfgp_….
status planned; nach expires_at expired.
expires_at Der Plan ist 1 Stunde gültig. Er wird 7 Tage nach Ablauf gelöscht.
summary Anzahl der Aktionen create, update, delete und no_op.
changes Ein Eintrag pro Ressource, in Typreihenfolge und dann nach key.
warnings secret_required: Die Verbindung benötigt ein Client-Secret, das das Ziel noch nicht hat.

Jede Änderung hat kind, key, action (create, update, delete oder no_op), object_version (die Version der Zielressource zum Planzeitpunkt; null bei create), requires_secret, fields und bei create und update den gewünschten spec. Jeder Eintrag in fields ist ein Feldunterschied: pointer (RFC 6901, zum Beispiel /spec/name), op (add, remove oder replace wie in RFC 6902), before und after. Listen werden als ganze Werte verglichen.

Ein unverändert übergebenes exportiertes Dokument plant für jede Ressource no_op, unabhängig von der Reihenfolge der Ressourcen und mengenartigen Listen.

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

Jeder Plan schreibt einen Eintrag config_plan.created in das Verwaltungsprotokoll der Umgebung.

Grenzen

Fehler

HTTP code Wann
400 malformed_request, unknown_field Der Body ist kein JSON oder enthält ein anderes Feld als document und prune.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder widerrufen.
403 insufficient_permissions Den Anmeldedaten fehlt eine erforderliche Berechtigung; required_permissions listet alle auf.
413 config_document_too_large, payload_too_large Das Dokument hat mehr als 5.000 Ressourcen oder 10 MiB; planen Sie weniger Typen.
422 validation_failed Siehe unten; errors[].pointer zeigt in die Anfrage (/document/...).
429 rate_limited Das Planlimit oder das Plankontingent der Umgebung ist erreicht, oder die Umgebung berechnet zu viele Pläne; wiederholen Sie nach der Retry-After-Zeit (beim Kontingent, wenn der älteste Plan abläuft oder gelöscht wird).
503 service_unavailable Die Planberechnung ist ausgelastet oder eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie nach der Retry-After-Zeit.
errors[].code Bedeutung
required document fehlt.
invalid Das Dokument entspricht an diesem Pointer nicht dem Schema.
duplicate Zwei Ressourcen haben dieselbe kind und key.
kind_not_listed Der Typ der Ressource steht nicht in kinds.
secret_value Ein geheimer Wert wurde gefunden; verwenden Sie einen secret_ref-Platzhalter.
unresolved_reference Der referenzierte key würde nach der Änderung nicht existieren.
key_in_use Der key gehört zu einer Anwendung, die nicht über die Konfiguration verwaltet wird (organisationseigen oder selbst registriert), oder zur System-API.
still_referenced /prune: Eine verbleibende Ressource verweist auf eine Ressource, die der Plan löschen würde.
too_large Eine Ressource, eine Warnung oder ein Feld der obersten Ebene hat mehr als 200.000 JSON-Werte.
too_long settings einer Verbindung überschreitet 32 KiB, oder jwks einer Anwendung bzw. consent_text_i18n einer Berechtigung überschreitet 16 KiB.
too_deep settings einer Verbindung ist tiefer als 8 Ebenen verschachtelt.
reserved Der identifier der API liegt im Namensraum urn:idp: der Plattform.

Beispiel

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