Secrets

The Secrets package describes how an application refers to stored credentials by name. The platform's custody service stores the values. The egress gateway adds them to your backend's calls to external application programming interfaces (APIs). An application's platform credential and its database connection are separate credentials, which the platform injects itself.

Use it when

Use the custody service for a third-party API key that the gateway adds to each call to a declared upstream. Use it also for a secret your code must read itself, bound to a setting. Store the value through your tool from a local file or an environment variable, and refer to it by name in declarations, code, and documentation.

The custody actions manage no signing key you supply and no delegated token. Storing a value provides no signing service and no token refresh. The signing keys of each end-user realm are the platform's own, as Verifying an end user describes.

Use ordinary configuration for feature flags and other values that are not secret. No action returns a stored value. If you lose your copy, get a new one from its issuer and store it again.

What it provides

  • Write-only storage with a list of names. list_secrets lists names, scopes, timestamps, and the settings a manifest binds each name to, never values. An application scope covers one environment, development or production, and a value stored at one environment is never read for the other. One name may have a value at each environment's scope. An account-scoped value is used for both environments' upstream calls. store_secret, rotate_secret, and delete_secret take an optional environment that defaults to production.
  • Replacement without a redeploy. Replace a stored upstream key, and the gateway uses the new value on later calls in the request's environment.
  • Settings bound by the manifest. A value your code reads itself is bound to a named setting in the manifest's settings member. Each deploy and promote injects the value stored for its environment. A replacement takes effect at the next deploy or promote, or at a restart where the running copy already has the binding. Store a secret explains the protection a binding gives up.
  • Guidance to replace a credential disclosed in chat, logs, or committed files.
  • Removal with what uses the value, or when you delete it. delete_secret removes one entry you name, once you approve it in the browser. It refuses a name a manifest binding, an upstream, a sign-in method, or a push provider still uses (Store a secret). Deleting the application removes its application-scoped entries in every environment. delete_environment removes the development environment's entries, its platform credential included. Account-scoped entries remain until you delete them or the account is deleted. After removal, the vault keeps a deleted value for ninety days before it purges it, the period the privacy policy states. No action of yours can read or restore the value in that time.

The platform-minted names are the environment's platform credential, credential-<application id>, the database credential, and the issue-tracking space's first token, issue-tracking-<application id>, which has the space's highest permission level. store_secret and delete_secret refuse all three. rotate_secret refuses the issue-tracking token at every scope. On the development scope only, it mints a new value for each of the other two and returns it once. On the production scope it refuses them, because only a promote, or a deploy to production on an application with one environment, rotates the production values.

The new development value is returned only over the HTTP API. A call through the Model Context Protocol (MCP) tool is refused with 409 local_route_required before anything is written. Your tool calls submit_manifest with the application, its manifest, and local_run: true, and runs the provision line it returns. The line makes the HTTP calls and writes each value into the development environment file.

Every promote mints a new production platform credential, and so does every deploy to production on an application with one environment. The new value goes into the new container while the current value stays in use. Custody switches to the new value only when the health check passes, so a failed promote or deploy changes nothing.

The previous value keeps working on the storage, logging, and egress services, and nowhere else, for at most the interval Sign-in, sessions, and tokens states. A promote or such a deploy with rotate_database_credential: true also sets a new production database password, and a roll_back mints a new platform credential only. Neither new value is ever returned.

Availability

Version 0.17.0 is the package's current version, and list_library reports the version the platform currently publishes. The custody actions are store_secret, rotate_secret, list_secrets, and delete_secret. A value goes over the HTTP API only, sent by the command line a store_secret or rotate_secret call returns (Store a secret): the MCP tools of the same names take none. The entry contains the package's contracts and its integration guide, and no client module to import. The platform runs and tests the behaviour they describe.

A store_secret call naming generate has the platform create a value nobody chooses in custody, at one environment of an application, and returns none (When no person is present).

The egress gateway reads the credential for a declared upstream call. It reads a value stored under an application's scope from the hosting cell's application vault, and a value stored at the account's scope from the platform's account vault. It reads from no other vault.

The platform also reads the token of each issue-tracking space your applications and your account use. The platform stores the token when it creates the space. An application's own space, shared by both environments, has one token, stored under the application's production scope in the cell's application vault. An application with a space for each environment has one token for each, under that environment's scope. A space of your account's own has one token, stored at your account's scope in the platform's account vault.

The egress gateway reads the token for each call it forwards through its issue-tracking upstream, presents it to the issue service, and never returns it to the caller. A call from an application bound to a space of your account uses that space's token.

The management service reads a space's token for the acts made on that space: the feedback actions, relay_issue_act, a deploy's build row, the platform's daily copy, an account export, and deleting the space. It deletes an application's space when you delete the application, and every space when you delete your account. Where the application has a space for each environment, deleting the development environment deletes that environment's space under its token. No act returns the token.

Two values the egress gateway reads belong to the platform and to no account: the AI allowance's key and the issue service's gateway credential. Each is kept in the platform's own vault, not in any account's custody entry. The gateway reads each one through a separate reader used for that value alone. It presents the gateway credential to the issue service with the space token, and never returns it to the caller. No account can read either value, refer to it by name, or declare an upstream that uses it.

The deployment service and the accounts service also read stored values, for internal use. The deployment service reads an application's deployment credentials, and the values its manifest binds, only to inject them into that environment's copy. The accounts service reads a realm's configured work-account sign-in, the client secret of a company's Microsoft Entra sign-in, from the cell's realm vault. That vault contains realms' work-account client secrets and nothing else. A client secret moves there when configure_realm names it, and stays there while it exists. None of these reads is a management action that returns a stored value.

The egress gateway and the accounts service record each read of a stored value they make, with the application it was for and the time. No record holds the value. The platform keeps these records for thirteen months, as it keeps its other usage records, and then deletes them. No action returns them.

The platform keeps each end-user realm's signing keys, encrypted, in its custody. Only the accounts service reads them, to sign and re-issue session tokens. A key older than 180 days is replaced without any action from you, and revoke_realm_keys revokes a realm's keys. Verifying an end user describes both.

Egress provides the client for the calls to which the gateway adds a stored key. Account is the package whose realm signing keys are kept in the same custody. Store a secret gives the steps to store, bind, and delete a value. Call an external API with an API key shows how a stored key reaches an upstream without ever reaching the application.