Secrets

Three kinds of secret exist on the platform, and each has one home: an app's own secrets, encrypted with KMS and injected only into that app's sandbox; the platform's operator credentials, delivered to pods from Parameter Store; and a workspace's own vendor keys, held in Secrets Manager and reachable only through the counterparty registry. This chapter covers each and the rule that nothing else may hold a key.

#App Secrets

A builder stores secrets for their app: third-party API keys, external database URLs, and webhook signing secrets. Each secret has separate dev and prod values, so development never runs with production credentials.

Values are encrypted with a KMS key before they are written to the platform database, and decrypted only when a sandbox is configured for a release. The platform lists secret names to the dashboard and never returns values. At configure time the platform resolves the values for the environment (dev or prod), decrypts them, and passes them into the sandbox as environment variables for the app's code. Nothing else reads them, and they exist in plaintext only inside that app's VM. A change to a secret stops the app's sandboxes, so no pod runs with stale values.

#Operator Credentials

The platform's own credentials, the keys it uses to call model providers, payment, email, telephony, and the rest, live in AWS Systems Manager Parameter Store. External Secrets Operator syncs them into a Kubernetes Secret on a short refresh interval, and every role's Deployment mounts the whole Secret and the whole ConfigMap. A build-time validator asserts that every environment variable the code reads is present in every manifest that runs it, so a Deployment cannot drift from the set the code expects.

Inside the code, an operator credential is readable in exactly one place: a single accessor in the counterparty registry, keyed by the surface that declares the environment variable. No adapter, step, or service reads a vendor key from configuration or from the environment directly, and two CI assertions keep it that way: no file outside the registry reads a variable a surface declares, and the shared constants module exports no name a surface declares.

#Workspace Keys

A workspace can bring its own key for a model provider or a service. Those keys live in one AWS Secrets Manager bundle per workspace, a JSON document keyed by service, with a version counter in the platform database that every write bumps. Decrypted bundles are cached under the workspace and version, so a stale credential is structurally impossible after a rotation.

A workspace key is obtainable only through the registry's clearinghouse, which also honors the workspace's enable and disable toggles. When a workspace has its own key for a provider, the adapter is constructed with that credential and usage is billed under the workspace's own-key events. See Counterparties and Egress.

#The Rule

A credential can be obtained only through the registry. With a workspace in hand, code takes one path: it honors the workspace's settings and its own key, and resolves asynchronously. Without a workspace in hand, code takes the other: it returns the deployment's own operator key, synchronously. Every adapter takes a resolved credential in its constructor, and every step reaches credentials through its context. There is no third path.

#Encryption Keys

Customer-managed KMS keys back the platform database, the app-secrets envelope, the container registry, and the backup vaults. Object storage is encrypted at rest with server-side encryption. TLS terminates at the edge and again at the load balancer, and is required on every database connection.