Configuration and secrets

The model declares what configuration an application needs. The runtime control plane supplies environment-specific values. Secret contents never belong in the model, generated files, logs, or release metadata.

What belongs where

Value	Location
“Payment provider uses an API key”	Integration model
Environment variable name PAYMENTS_API_KEY	Model/config manifest
Production key value	Secret store/control plane
Provider endpoint name and purpose	Integration model
Staging versus production endpoint value	Environment configuration
Password policy	Auth add-on model
JWT signing secret	Secret store

This distinction lets the same release run in preview, staging, and production without rebuilding solely to change a credential.

Generated contract

Generated applications should publish a configuration manifest or sample environment file that documents:

• variable name;
• required or optional status;
• non-secret description;
• allowed format or enum;
• which subsystem consumes it;
• whether a restart is required.

Sample files contain placeholders, never usable credentials.

Startup behavior

Required secrets must fail closed. An authentication module with no signing key must not silently generate an ephemeral key and start. Integration status endpoints can distinguish configured, missing, and unreachable dependencies without revealing values.

Readiness should fail only for dependencies required to serve current traffic. Optional integrations can report degraded status while the application remains available if the product defines that behavior.

Rotation

Use a staged rotation when consumers need overlap:

1. add the new credential at the provider;
2. update the control plane;
3. verify consumers use it;
4. revoke the old credential;
5. record the operational change.

If the application must accept two signing keys during rotation, that capability is part of the generated/runtime contract and may require a release.

API incidents

• Endpoint or key changed, contract unchanged → update configuration.
• Provider behavior or payload changed → update integration model or adapter and regenerate.
• Provider is temporarily down → use resilience and operational controls.
• A secret was exposed → rotate immediately, audit use, then rebuild only if source or artifacts contained it.

Local development

Use ignored local environment files or a developer secret manager. Never copy production credentials into preview. Generated documentation should list requirements so developers do not need to inspect source to discover configuration.

See External systems and Incidents.