Plan a configuration change

POST /v1/config-plans · permission config:read and the read permission of each kind in the document

Compares a configuration document with the environment's current configuration and stores the result as a plan. Nothing is changed: a plan only shows what applying the document would do. Use it to review a promotion from development to staging or production before you apply it.

Request

• The document's kinds are kinds if given (every resource must then be of a listed kind), otherwise the kinds of its resources. Only these kinds are compared; other kinds are left as they are.
• A resource missing from the document is not deleted unless prune is true. The singleton kinds (environment_settings, identity_settings, branding) are never deleted.
• In the singleton kinds, a field missing from the document is left unchanged: the target's current value is kept. A document exported before a field existed therefore does not reset that field. A value given explicitly, including null, is still written. In the other kinds, a missing field takes its default value.
• The document must not contain secret values. A secret field holds only a secret_ref placeholder or null; a value is rejected and is never echoed back.
• warnings in the document are ignored; at most 15,000 are accepted (an export never contains more).
• The permissions are those of an export of the same kinds. With prune, the kinds that may refer to a deleted resource are read too, so their permissions are required as well.

Response

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

Each change has kind, key, action (create, update, delete or no_op), object_version (the target resource's version at plan time; null for create), requires_secret, fields and, for create and update, the desired spec. Each entry in fields is a field difference: pointer (RFC 6901, for example /spec/name), op (add, remove or replace, as in RFC 6902), before and after. Lists are compared as whole values.

An exported document applied unchanged plans no_op for every resource, whatever the order of resources and set-like lists.

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

Every plan writes a config_plan.created entry to the environment's management log.

Limits

• Rate: plans have their own per-minute limit per environment: 20 on Free, 60 on Startup and Business, 120 on Enterprise in production; one tenth (at least 2) in development and staging.
• Quota per environment: at most 100 plans that are neither applied nor expired, and at most 2,000 plans and 1 GiB of stored plans until they are deleted (7 days after expiry). Plans of other environments never count.
• Capacity: the server computes a limited number of large plans at the same time; one environment can use at most a quarter of that capacity.
• Field limits are those the configuration service enforces when it writes: the schema bounds lists and texts (for example redirect_uris 50, allowed_web_origins 20, permissions 1,000), connection settings is at most 32 KiB and 8 levels deep, application jwks and each permission's consent_text_i18n at most 16 KiB.

Errors

Example

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