Planificar un cambio de configuración

POST /v1/config-plans · permiso config:read y el permiso de lectura de cada tipo del documento

Compara un documento de configuración con la configuración actual del entorno y guarda el resultado como un plan. No se cambia nada: un plan solo muestra lo que haría aplicar el documento. Úsalo para revisar una promoción de development a staging o production antes de aplicarla.

Solicitud

• Los tipos del documento son kinds si se indica (entonces cada recurso debe ser de un tipo listado); si no, los tipos de sus recursos. Solo se comparan estos tipos; los demás quedan como están.
• Un recurso que falta en el documento no se elimina salvo que prune sea true. Los tipos únicos (environment_settings, identity_settings, branding) nunca se eliminan.
• En los tipos singleton, un campo que falta en el documento no cambia: se conserva el valor actual del destino. Así, un documento exportado antes de que existiera un campo no restablece ese campo. Un valor indicado explícitamente, incluido null, se sigue escribiendo. En los demás tipos, un campo que falta toma su valor predeterminado.
• El documento no debe contener valores secretos. Un campo secreto solo contiene un marcador secret_ref o null; un valor se rechaza y nunca se devuelve.
• Los warnings del documento se ignoran; se aceptan como máximo 15.000 (una exportación nunca contiene más).
• Los permisos son los de una exportación de los mismos tipos. Con prune también se leen los tipos que pueden hacer referencia a un recurso eliminado, así que sus permisos también son necesarios.

Respuesta

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

Cada cambio tiene kind, key, action (create, update, delete o no_op), object_version (la versión del recurso de destino al planificar; null en create), requires_secret, fields y, en create y update, el spec deseado. Cada entrada de fields es una diferencia de campo: pointer (RFC 6901, por ejemplo /spec/name), op (add, remove o replace, como en RFC 6902), before y after. Las listas se comparan como valores completos.

Un documento exportado enviado sin cambios planifica no_op para cada recurso, sea cual sea el orden de los recursos y de las listas de tipo conjunto.

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

Cada plan escribe una entrada config_plan.created en el registro de gestión del entorno.

Límites

• Frecuencia: los planes tienen su propio límite por minuto y entorno: en production, 20 en Free, 60 en Startup y Business, 120 en Enterprise; en development y staging, una décima parte (al menos 2).
• Cuota por entorno: como máximo 100 planes que no se hayan aplicado ni caducado, y como máximo 2.000 planes y 1 GiB de planes almacenados hasta que se eliminan (7 días después de caducar). Los planes de otros entornos nunca cuentan.
• Capacidad: el servidor calcula un número limitado de planes grandes a la vez; un entorno puede usar como máximo una cuarta parte de esa capacidad.
• Límites de campos: son los que el servicio de configuración aplica al escribir: el esquema limita listas y textos (por ejemplo redirect_uris 50, allowed_web_origins 20, permissions 1.000), los settings de una conexión tienen como máximo 32 KiB y 8 niveles de profundidad, y los jwks de una aplicación y el consent_text_i18n de cada permiso como máximo 16 KiB.

Errores

Ejemplo

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