ReferenceAsk
Remy Reference/Architecture/Identity & Security/Secrets
18Identity & Security

Secrets

The three kinds of secret the platform holds, where each one lives, and the single path by which any credential is obtained.

Two kinds of stored secret exist on the platform, and one module seals both before they reach the database. The first is an app's own secrets, injected into that app's sandbox. The second is vendor keys, held in one credential store and reachable only through the counterparty registry. These cover each workspace's own keys and the platform's own keys for the same vendors. This chapter covers each kind, the key they are sealed under, 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 a dev value and a prod value, so a builder can use test credentials while building and on branch previews, and live ones in production. Either value may be left empty, and an empty one falls back to the other. A builder who sets only a prod value runs their dev box and previews with it.

Values are sealed before they are written to the platform database. A listing returns names and which values are set, never the values. When a sandbox is configured, the platform resolves the values for its environment: a dev session and a branch preview get dev values, and a live release gets prod values. It decrypts them and passes them into the sandbox as environment variables for the app's code. A change to a secret stops the app's sandboxes, so no pod runs with stale values.

Two other paths read them, and both are deliberate:

  • The workspace's builders can reveal a value in the dashboard or the admin CLI, and every reveal is audited. Staff impersonating a builder cannot reveal a value. The reveal is refused, and the refusal is audited too.
  • A data-source connector that follows a customer's own S3 bucket names two of the app's secrets as its access keys. The platform decrypts their prod values to list and read the bucket.

#Vendor Keys

Any key a workspace brings for a model provider or a service is a row in the credential store. So is the platform's own key for each vendor a workspace can bring one for, such as the model providers, the data APIs, and the rest a workspace can put on its own key. A row holds one service's declared fields, sealed together, and a listing returns previews, never values. A database dump holds only ciphertext, and the key that opens it is not in the dump.

The platform's other vendor keys are part of how the deployment is wired, and they stay in its configuration. They cover the CDN, payments, warehouse, telemetry, mail relay, telephony, CRM, and OAuth app registrations. In the cloud they live in AWS Systems Manager Parameter Store, synced into the Kubernetes secret. On a self-host they live in the environment.

Deployment admins manage the platform's keys in the store on the Keys page of the operator console. For each surface, the page shows its key, where it comes from, when it last changed, and by whom. A self-host's operator can also manage them with the admin CLI, behind the box's own operator token, and the install sets the first model keys that way. Setting a key goes through these steps:

  1. For a model provider, the platform checks the key with the vendor first.
  2. It records the change in the deployment keys' own history.
  3. It announces the change.
  4. Every process holding the keys reloads its copy within seconds, so a rotation needs no restart.

The processes holding them are the HTTP and worker roles, the ones that call these vendors for a workspace. Each loads the keys before it builds anything, and one that cannot load them does not start. A deploy that cannot read the keys therefore never replaces pods that can. No other role reads the store.

A workspace's keys are cached under the workspace and a version that every write to the workspace's keys bumps, 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: an asynchronous call that honors the workspace's settings and its own key. Without a workspace in hand, code takes the other: a synchronous call that returns the deployment's own key. Every adapter takes a resolved credential in its constructor, or reads it at the moment it calls. Every step reaches credentials through its context. There is no third path.

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.


#Encryption Keys

A stored secret is sealed under a fresh data key, and a key from a registry seals that data key. The value carries the id of the registry key. In the cloud, that key is a customer-managed KMS key the platform never holds, and each encrypt and decrypt is one KMS call. A self-hosted deployment has a key of its own instead, generated at setup, and it loses what is sealed under that key if it loses the key. Because every value names its key, one database can hold values from both. A rotation is a new key made active beside the old.

Customer-managed KMS keys also back the platform database, 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 and cache connection. The Valkey cache is encrypted at rest and admits one user, the platform's, which signs in with short-lived IAM tokens. Unauthenticated connections are refused. See Portability for the self-hosted profile.

What This Gives an App and Its Workspace
Secrets that are encrypted at rest, never listed, and shown only to the app's builders, on request and audited.
Separate values for development and production, each falling back to the other when unset.
The option to bring their own vendor keys, honored everywhere the platform calls that vendor.
A platform whose keys for those same vendors sit behind one door, reach only the code that asks for them, and change without a restart.