Planifier une modification de configuration

POST /v1/config-plans · permission config:read et la permission de lecture de chaque type du document

Compare un document de configuration à la configuration actuelle de l'environnement et enregistre le résultat sous forme de plan. Rien n'est modifié : un plan montre seulement ce que ferait l'application du document. Utilisez-le pour examiner une promotion de development vers staging ou production avant de l'appliquer.

Requête

• Les types du document sont kinds s'il est fourni (chaque ressource doit alors être d'un type listé), sinon les types de ses ressources. Seuls ces types sont comparés ; les autres restent inchangés.
• Une ressource absente du document n'est pas supprimée sauf si prune vaut true. Les types singletons (environment_settings, identity_settings, branding) ne sont jamais supprimés.
• Dans les types singletons, un champ absent du document reste inchangé : la valeur actuelle de la cible est conservée. Un document exporté avant l'ajout d'un champ ne réinitialise donc pas ce champ. Une valeur donnée explicitement, y compris null, est toujours écrite. Dans les autres types, un champ absent prend sa valeur par défaut.
• Le document ne doit contenir aucune valeur secrète. Un champ secret ne contient qu'un espace réservé secret_ref ou null ; une valeur est rejetée et n'est jamais renvoyée.
• Les warnings du document sont ignorés ; 15 000 au plus sont acceptés (un export n'en contient jamais davantage).
• Les permissions sont celles d'un export des mêmes types. Avec prune, les types pouvant référencer une ressource supprimée sont aussi lus, leurs permissions sont donc également requises.

Réponse

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

Chaque modification contient kind, key, action (create, update, delete ou no_op), object_version (la version de la ressource cible au moment du plan ; null pour create), requires_secret, fields et, pour create et update, le spec souhaité. Chaque entrée de fields est une différence de champ : pointer (RFC 6901, par exemple /spec/name), op (add, remove ou replace, comme dans RFC 6902), before et after. Les listes sont comparées comme des valeurs entières.

Un document exporté fourni sans modification planifie no_op pour chaque ressource, quel que soit l'ordre des ressources et des listes de type ensemble.

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

Chaque plan écrit une entrée config_plan.created dans le journal de gestion de l'environnement.

Limites

• Débit : les plans ont leur propre limite par minute et par environnement : en production, 20 en Free, 60 en Startup et Business, 120 en Enterprise ; en development et staging, un dixième (au moins 2).
• Quota par environnement : au plus 100 plans ni appliqués ni expirés, et au plus 2 000 plans et 1 Gio de plans stockés jusqu'à leur suppression (7 jours après l'expiration). Les plans des autres environnements ne comptent jamais.
• Capacité : le serveur calcule un nombre limité de grands plans à la fois ; un environnement peut utiliser au plus un quart de cette capacité.
• Limites de champs : ce sont celles que le service de configuration applique à l'écriture : le schéma borne les listes et les textes (par exemple redirect_uris 50, allowed_web_origins 20, permissions 1 000), les settings d'une connexion font au plus 32 Kio et 8 niveaux de profondeur, les jwks d'une application et le consent_text_i18n de chaque permission au plus 16 Kio.

Erreurs

Exemple

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