Pianificare una modifica della configurazione

POST /v1/config-plans · permesso config:read e il permesso di lettura di ogni tipo nel documento

Confronta un documento di configurazione con la configurazione attuale dell'ambiente e salva il risultato come piano. Non viene modificato nulla: un piano mostra solo cosa farebbe l'applicazione del documento. Usalo per verificare una promozione da development a staging o production prima di applicarla.

Richiesta

• I tipi del documento sono kinds se indicato (ogni risorsa deve allora essere di un tipo elencato), altrimenti i tipi delle sue risorse. Vengono confrontati solo questi tipi; gli altri restano invariati.
• Una risorsa assente dal documento non viene eliminata a meno che prune sia true. I tipi singleton (environment_settings, identity_settings, branding) non vengono mai eliminati.
• Nei tipi singleton un campo assente dal documento resta invariato: viene mantenuto il valore attuale della destinazione. Un documento esportato prima che un campo esistesse quindi non reimposta quel campo. Un valore indicato esplicitamente, null compreso, viene comunque scritto. Negli altri tipi un campo assente assume il valore predefinito.
• Il documento non deve contenere valori segreti. Un campo segreto contiene solo un segnaposto secret_ref o null; un valore viene rifiutato e non viene mai restituito.
• I warnings del documento vengono ignorati; ne sono accettati al massimo 15.000 (un'esportazione non ne contiene mai di più).
• I permessi sono quelli di un'esportazione degli stessi tipi. Con prune vengono letti anche i tipi che possono fare riferimento a una risorsa eliminata, quindi servono anche i loro permessi.

Risposta

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

Ogni modifica ha kind, key, action (create, update, delete o no_op), object_version (la versione della risorsa di destinazione al momento del piano; null per create), requires_secret, fields e, per create e update, lo spec desiderato. Ogni voce di fields è una differenza di campo: pointer (RFC 6901, ad esempio /spec/name), op (add, remove o replace, come in RFC 6902), before e after. Gli elenchi vengono confrontati come valori interi.

Un documento esportato inviato senza modifiche pianifica no_op per ogni risorsa, indipendentemente dall'ordine delle risorse e degli elenchi di tipo insieme.

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

Ogni piano scrive una voce config_plan.created nel registro di gestione dell'ambiente.

Limiti

• Frequenza: i piani hanno un proprio limite al minuto per ambiente: in production 20 su Free, 60 su Startup e Business, 120 su Enterprise; in development e staging un decimo (almeno 2).
• Quota per ambiente: al massimo 100 piani né applicati né scaduti, e al massimo 2.000 piani e 1 GiB di piani archiviati fino alla loro eliminazione (7 giorni dopo la scadenza). I piani di altri ambienti non contano mai.
• Capacità: il server calcola un numero limitato di piani grandi contemporaneamente; un ambiente può usare al massimo un quarto di questa capacità.
• Limiti dei campi: sono quelli che il servizio di configurazione applica in scrittura: lo schema limita liste e testi (ad esempio redirect_uris 50, allowed_web_origins 20, permissions 1.000), i settings di una connessione sono al massimo 32 KiB e 8 livelli di profondità, i jwks di un'applicazione e il consent_text_i18n di ogni permesso al massimo 16 KiB.

Errori

Esempio

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