Secrets #

View this page as Markdown

On this page

The Secrets package describes how your 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). Your application's platform credential and its database connection are separate credentials, which the platform injects itself. Store a secret is the task, step by step.

To store a key, your tool calls store_secret with no value and runs the line it returns, which reads the value from a file or from what you type. That route keeps the value out of the chat. If you deliberately supplied a value in the conversation, your tool may pass it to store_secret as value. Then use the key, as Store a secret shows: a declare_outbound_api call names it as the key for an outside API, or the manifest's settings binds it to a setting your code reads.

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.

Your code reads a bound secret from process.env under its setting name; Bind a stored value to a setting shows the binding and the JavaScript read.

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.

Feature flags and other values that are not secret are not stored here. Write each in the manifest's settings member as {"value": "<text>"}, which every deploy and promote sets as a plain setting (Set a value that is 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. The action 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. The actions store_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. Replace a value gives a replacement's steps and its check. Store a secret explains the protection a binding gives up.
  • A way to tell which value a running copy has. list_secrets lists two fingerprints per environment row: short codes computed from values with a platform key. fingerprint identifies the value stored now, and applied_fingerprint identifies the value the running copy received when it last started. Where they are equal, the copy has the stored value. Where they differ, a restart applies the stored value, and read_status lists the name in settings_mismatch. Fingerprints cannot reveal the value; storing a guess under another name produces a different fingerprint. A value stored, or copy started, before fingerprints were recorded has a null fingerprint. Verify a rotation gives the steps.
  • Which value the gateway sends. The egress gateway keeps no copy of a value and reads the stored one on every call it forwards. The fingerprint on the application's environment row identifies the value the next call sends. If that environment has no stored value, the gateway reads the account-scoped row instead, and that row's fingerprint identifies the value. request_route on a route that calls the upstream, naming the environment, shows whether the upstream accepts it.
  • Which services use a name. Each environment row lists consumers: its sign-in route when the name is a work-account client secret or Apple signing key, and its push configuration for a provider credential. It also lists an upstream bound to the application if that upstream declares the name as its credential. Account-scoped rows list no consumers, even when an upstream uses the value.
  • Guidance to replace a credential disclosed by accident in chat, or exposed in logs or committed files.
  • Removal when you delete the value or what uses it. Calling 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. The action 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, then purges it, the period the privacy policy states. No action of yours can read or restore it then.

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. Without replace: true, store_secret refuses all three, and delete_secret always refuses them. With replace: true, store_secret refuses the issue-tracking token at every scope, and the other two on the production scope. On the development scope it mints a new value for each of those two and returns it once, over the HTTP API only.

That development-scope store_secret call with replace: true, made through the Model Context Protocol (MCP) tool, is refused with 409 local_route_required before anything is written. Your tool runs turnzero provision --application <application id> with nothing piped, makes any submit_manifest call it prints, and runs the provision line that call returns. The line makes the HTTP calls and writes each value into the development environment file.

Production credentials rotate only on a promote or on a deploy to production for an application with one environment. Each operation creates a new production platform credential for the new container. The current container keeps using the old value until the new container passes its health check. Only then does the platform switch to the new credential. A failed promote or deploy leaves the current value unchanged.

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. 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.

Availability #

Version 0.22.4 is the package's current version, and this page describes it. Until the library's next publish, read_library can return an earlier version, the one you can take, so this page can describe a change that version lacks.

The custody actions are store_secret, list_secrets, and delete_secret. To replace a value, call store_secret with replace: true. A value goes over the HTTP API, sent by the command line that call returns (Store a secret). For the conversation exception described above, the store_secret tool takes value, including with replace: true. The entry contains the package's contracts and its integration guide, and no client module to import.

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

Who reads a stored value #

No management action returns a stored value. The platform's own services read values for these uses alone:

  • 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 egress gateway reads the token of each issue-tracking space your applications and your account use, for each call it forwards, and presents it to the issue service, never returning it. A call from an application bound to a space of your account uses that space's token. The platform stores each token when it creates the space: an application's own space has one, under its production scope in the hosting cell's application vault. A space of your account's own has one at your account's scope.
  • The management service reads a space's token for each operation it performs on that space: the feedback actions, relay_issue_act, a deploy's build row, the daily copy, an account export, and deleting the space.
  • 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 work-account sign-in, the client secret of a company's Microsoft Entra sign-in, from the hosting cell's realm vault. That vault contains realms' work-account client secrets and nothing else. A client secret moves there when you name it in a configure_app_sign_in call, and stays there while it exists.
  • The accounts service alone reads each realm's signing keys, kept encrypted in the platform's custody, to sign and re-issue session tokens. A key older than 180 days is replaced without any action from you, and revoke_app_sign_in_keys revokes a realm's keys.

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, read through a reader used for that value alone, and never returned. No account can read either value, refer to it by name, or declare an upstream that uses it.

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 contains 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.

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.