---
title: Store a secret
description: Store an API key by name, call its API through the gateway, replace or remove it, and supply the value without pasting it into chat.
slug: /getting-started/store-a-secret
order: 7
visibility: public
redirects_from: []
---

# Store a secret

Store an API key, password, or signing secret out of chat and source code. Add, replace, or remove it and choose how your app uses it.

For an API key:

- Your new or changed code [calls the gateway](/cloud/guides/call-an-external-api-with-an-api-key/#3-call-it-from-a-route). The gateway adds your stored key before forwarding a call.
- An unchanged SDK or code already reading its base URL and bearer key from settings uses [`sdk_settings`](#the-rule-in-code).
- Bind it only if its host is fixed in code the task forbids changing; add [`egress`](#the-rule-in-code).

For a value the code uses itself, such as a webhook signing secret, [bind it](#bind-a-value-to-a-setting).

Prompt:

> The backend needs my weather API key. Keep it for the app without me pasting it into this chat.

Also works:

- "Save the Anthropic key from my .env.local for this project."
- "The key I stored last month leaked. Replace it."
- "Which keys does this account already hold?"
- "Stripe gave me a webhook signing secret. Make it available to the backend."
- "I stored that key under the wrong name. Remove it."

To store it yourself, sign in at turnzero.ai and open **Secrets** → **Add a secret**. Enter its name, value, and scope, then choose **Save secret**. Your AI confirms the name with `tzcloud_list_secrets`.

## What your tool does

- Reads the `store-key` skill (`read_context`, id `skill:store-key`) and follows its ten rules, explained here and in [Keep a secret value out of chat](/cloud/guides/supply-a-secret-value-without-exposing-it/). Keeps the value out of code, the manifest, committed files, and tool calls. If you deliberately shared the value in the conversation, `tzcloud_store_secret` accepts it as `value`.
- Asks you for the name, the scope, and the file holding the value, or whether you will type it. It never asks for the value.
- [Unattended](/cloud/guides/supply-a-secret-value-without-exposing-it/#when-no-person-is-present), the platform makes a random value at the AI's `generate` request. If the platform cannot make it, the AI writes a file, stores its value, and deletes it in one step. Issued values use a saved file or [machine-set variable](/cloud/guides/supply-a-secret-value-without-exposing-it/#read-the-value-from-a-variable-a-machine-sets).
- Asks for no browser approval: `tzcloud_store_secret` runs without an approval step, including when you pass `replace: true`. Only a deletion waits for your approval in the browser ([step 6: Delete a value](#6-delete-a-value)).
- After a rotation, confirms that the running copy has the new value ([Check that a rotation reached the running copy](#check-that-a-rotation-reached-the-running-copy)).
- Uses `turnzero provision --application <application id>` for development credentials, returned on the HTTP API only.

## What you need

- The secret value, saved in a file outside your application's folder or ready to paste into your own terminal, and a name you choose for it.
- The scope: your whole account, or one application in one environment, development or production.

## Before your AI starts

**For the AI tool:** If a step needs the person, ask and pause that step. Keep working on what needs no person. With nobody present, follow [this procedure](/cloud/guides/supply-a-secret-value-without-exposing-it/#when-no-person-is-present).

- Check that your Cloud connection is signed in ([Connect your AI assistant](/cloud/getting-started/connect-your-tool/)).
- `tzcloud_list_applications` returns the application's identifier.
- Check for Node.js 24 or later and npm, which run the returned npx command ([Prerequisites](/cloud/getting-started/prerequisites/)).

## Steps

For failures, see [Refusals](#refusals) or [Secrets](/cloud/troubleshooting/secrets/).

Each stored name has one use. A [declared upstream](/cloud/concepts/glossary/#declared-upstream)'s key stays at the egress gateway, which adds it to the application's calls to that API. A value the [manifest](/cloud/concepts/glossary/#manifest)'s `settings` bind enters the application's container as that [setting](/cloud/concepts/glossary/#setting) (environment variable).

Bind values the code uses itself, such as webhook signing secrets, in the manifest's `settings`. For an outside API key, read [The rule in code](#the-rule-in-code) before choosing an upstream or binding.

For API keys, read [Store an API key and call through the gateway](#store-an-api-key-and-call-through-the-gateway). For other values, read [Worked example: a webhook signing secret](#worked-example-a-webhook-signing-secret).

### Store an API key and call through the gateway

Here the backend calls a weather API, and its key stays at the gateway. For a client whose host is fixed in code the task forbids changing, bind the key instead ([The rule in code](#the-rule-in-code)).

1. **Store.** Ask the person to save the key in a file outside the application's folder. Then call `tzcloud_store_secret` with these members and run `command_npx` once, exactly as returned (`command_npx_windows` on Windows). It prints `stored:` ([step 2: Supply the value without exposing it](#2-supply-the-value-without-exposing-it)).

```json
{
  "name": "WEATHER_API_KEY",
  "application": "<application id>",
  "environment": "production",
  "value_file": "../secrets/weather-api-key.txt"
}
```

2. **Declare.** You declare the upstream with `tzcloud_declare_outbound_api`, the stored name as its `credential_name`, as [Declare the upstream](/cloud/guides/call-an-external-api-with-an-api-key/#2-declare-the-upstream) shows.
3. **Call.** The backend calls the upstream's route on the gateway, which adds the key, as [Call it from a route](/cloud/guides/call-an-external-api-with-an-api-key/#3-call-it-from-a-route) shows.

For local runs, also store the name with `environment` `development`, or once at account scope ([step 1: Choose the name and the scope](#1-choose-the-name-and-the-scope)).

### Worked example: a webhook signing secret

The backend checks each Stripe webhook with the endpoint's signing secret. The code uses the secret itself, so it is bound as `STRIPE_WEBHOOK_SECRET`.

1. **Store.** For each hosted environment, call `tzcloud_store_secret` with `name: "stripe-webhook-secret"`, the `application`, and the `environment`. If the person deliberately shared the value in this conversation, pass it as `value`, without `value_file`. Otherwise, give the path of a file outside the application's folder as `value_file`, omit `value`, and run the returned command.
2. **Bind.** Add `"STRIPE_WEBHOOK_SECRET": { "secret": "stripe-webhook-secret" }` to the manifest's `settings` and resubmit the manifest with `tzcloud_submit_manifest`. Steps 1 and 2 (Store and Bind) run in either order. `tzcloud_submit_manifest` accepts a binding whose name is not stored yet, its `next` naming each `tzcloud_store_secret` call still owed. Only step 3 (Deploy) needs the value.
3. **Deploy.** A `tzcloud_deploy` or a `tzcloud_promote` injects its environment's value as `STRIPE_WEBHOOK_SECRET`, which the code reads from `process.env`. Either is refused `setting_secret_missing` where its environment has no value under the name.
4. **Rotate.** After the person replaces the secret at Stripe, call `tzcloud_store_secret` with `replace: true` and the same name, application, and environment, and run the command. `tzcloud_read_status` then lists the setting in `rotated_since_read`.
5. **Restart.** Once the command ends with status 0, you make the `tzcloud_restart_application` call the response's `next` gives. The new copy reads the new value, because the running copy already has the binding ([Restart an environment](/cloud/guides/manage-versions-and-environments/#restart-an-environment)). [Check that a rotation reached the running copy](#check-that-a-rotation-reached-the-running-copy) confirms it.

### The rule in code

A task that names a variable or describes existing code does not, by itself, forbid changing that code. A request to keep a variable name keeps the name, not the code that uses it. The task forbids changing code only where the person asks you to leave it as it is, or another explicit restriction in the task says so.

For new or changed code you own, declare the upstream and send the platform credential as [Call it from a route](/cloud/guides/call-an-external-api-with-an-api-key/#3-call-it-from-a-route) shows. Existing code that already reads both its base URL and key from settings and sends the key as `Authorization: Bearer` may keep that code and use `sdk_settings`. If that key already has a binding in `settings`, follow [Move code that reads the key from an environment variable](/cloud/guides/call-an-external-api-with-an-api-key/#move-code-that-reads-the-key-from-an-environment-variable) to replace the binding before the next deploy.

Bind the key instead only if the client's host is fixed in code the task forbids changing. Unless the person says otherwise, you may change the application's own code within the task, but not a library's source.

An SDK that reads its base URL and key from settings, such as OpenAI's, keeps its code unchanged: declare its upstream with `sdk_settings`, as [An unchanged SDK](/cloud/guides/call-an-external-api-with-an-api-key/#an-unchanged-sdk) shows.

The manifest's `settings` binds a stored name to a setting the application's code reads. `tzcloud_declare_outbound_api`'s `sdk_settings` is a different member: it names the settings an unchanged SDK reads, the gateway's address and an [egress key](/cloud/concepts/glossary/#egress-key), while the stored key stays at the gateway ([An unchanged SDK](/cloud/guides/call-an-external-api-with-an-api-key/#an-unchanged-sdk)).

A key an upstream declares is read by the gateway on every call, so a rotation reaches the next call with no restart. Only a value bound to a setting waits for the restart the worked example makes.

The same declaration can live in the manifest instead, as an entry of `upstreams` keyed by its name and without `application`. There, a key not stored yet is accepted, and the gateway refuses the upstream's calls until `tzcloud_store_secret` stores it. [Declare an upstream in the manifest](/cloud/guides/author-the-manifest/#declare-an-upstream-in-the-manifest) shows the entry.

The wrong choice does not fail at the deploy. An upstream declared for a client whose host is fixed never reaches that client. The client calls its host directly and sends the [egress key](/cloud/concepts/glossary/#egress-key), or no key, in place of your stored one. The deploy still passes its health check, and the call then fails: the provider refuses it, or the platform does once the application enforces its egress list.

The platform cannot confirm this exception: nothing the platform stores identifies the host receiving a bound value, and no platform check inspects your code for that choice. Check the client's host in the code yourself. If an `egress` entry allows a declared upstream's host, `tzcloud_submit_manifest` returns `egress_notice`. A direct call carries no key added by the gateway, and the checks below cannot show one.

After the first deploy, have the application make a call that uses the key. Read that environment's logs with `filter: "undeclared"` and `source: "egress"`, then with `source: "harness"`. The [runtime harness](/cloud/concepts/glossary/#runtime-harness) is the platform code running in the application process.

A record naming the provider's host shows a direct call, not which key it carried. Correct the client to use the gateway. Bind the key and list the host in `egress` only if the task forbids changing the code that fixes the client's host.

A maps client whose host is fixed in code the task forbids changing is that exception. Store it as `maps-api-key`, then bind it in the manifest's `settings`, and the code reads `process.env.MAPS_API_KEY`. The client calls its host directly, so list that host, `maps.example.com` here, in the manifest's `egress`, as [Writing the egress list](/cloud/guides/author-the-manifest/#writing-the-egress-list) describes.

```json
"settings": {
  "MAPS_API_KEY": { "secret": "maps-api-key" }
},
"egress": ["maps.example.com"]
```

### 1. Choose the name and the scope

The project and conversation refer to a secret by name. No action reads a stored value back, and storing a value does not protect a copy of the value already in a transcript, a log, or a repository.

`tzcloud_store_secret` takes a `name`, an optional `application`, and an optional `environment`: `development` or `production`, with `production` as the default. To replace a stored value, add `replace: true`. Pass `value` only when the person deliberately shared it in the conversation. Otherwise, leave `value` out and supply it through the command in step 2. A call with no `value` or `generate` stores nothing and returns that command.

The name has 1–64 letters, digits, underscores, or hyphens, and begins with a letter or digit. The value must not be empty, and its JavaScript string length must be at most 20,000.

A value is text: turnzero reads a value file as UTF-8 and refuses one holding a NUL character. To use a binary file, such as a `.p12`, `.pfx`, or `.jks` key store, store its base64 text, [bind it to a setting](#bind-a-value-to-a-setting), and decode the setting when the application starts. Write the base64 on one line, as `base64 -w 0` does on Linux and `[Convert]::ToBase64String` does in PowerShell, since line breaks count toward the 20,000 characters. On one line, base64 is a third longer than the bytes it encodes, so a file of up to 15,000 bytes fits.

A scope is the account, used by every environment, or one application in one environment. A development request never reads a production value, and neither environment falls back to the other. Leaving out `application` selects account scope. A scope holds at most 100 names: at an application's environment scope, every name stored there; at the account scope, the names you stored.

Every application has a development scope, even with one environment: a local run's calls through the gateway read its values. So `tzcloud_list_secrets` lists rows at the development scope even on an application with production alone, the platform's `credential-<application id>` among them: it is the platform credential a local run uses. For a test key in development and a live key in production, store the same name at each environment's scope.

A local run's calls through the gateway act in development, the environment its [platform credential](/cloud/concepts/glossary/#platform-credential) fixes, and read the key at the application's development scope, then at the account scope. So store a key a local run uses at the development scope, naming `application` and `environment` `development`, since `tzcloud_store_secret` defaults to `production`, or once at the account scope where both environments share it. A bound setting reads the application's own scope at each deploy and promote, never the account's.

A name stays at the scope you first stored it in, though the application's other environment may hold it too. For any other scope, use a new name.

### 2. Supply the value without exposing it

Recommend a file, the person's terminal, or the dashboard to keep the value out of chat history. The person may choose to paste a value into chat; `tzcloud_store_secret` accepts a value already shared there. That choice alone does not require rotation. Storing it in the vault does not remove that copy from the conversation.

For a value in a file, you call `tzcloud_store_secret` with the name, the scope, no value, and `value_file`. The file must stand outside the application's folder and hold the value alone.

For a `.env` line, choose a new file there and pass that path as `value_file`. In one shell step, write only the value without printing it, run the returned command, and delete the copy after the command ends. [When no person is present](/cloud/guides/supply-a-secret-value-without-exposing-it/#when-no-person-is-present) gives the procedure.

Run `command_npx` once, exactly as returned (`command_npx_windows` on Windows). Run it from the folder that a relative `value_file` path starts from, and the command prints `stored:`. The value enters no chat, tool call, or command line.

The returned command contains a short-lived credential called a [secret grant](/cloud/concepts/glossary/#secret-grant). It permits this one write and expires at `expires_at`. On macOS and Linux, an installed `command` for one application's scope has this form: `echo <grant> | turnzero secret store --name <name> --application <application id> --environment <environment> --value-file "<path>"`. Run the command returned by your call exactly as given, never this form.

[Keep a secret value out of chat](/cloud/guides/supply-a-secret-value-without-exposing-it/) covers the rest: the Windows and installed forms, the person typing the value in their own terminal, a tool with nobody present, and what the command prints.

### 3. Replace a value

A replacement has two parts. Storing the new value changes the value the platform holds. A bound setting reaches the running copy once a new copy starts: at the next deploy or promote, or at a restart where the copy already has the binding. An upstream's key is used from the gateway's next call.

`tzcloud_store_secret` with `replace: true` replaces an existing value at the same name, application, and environment. Only the stored value changes, and the application is not rebuilt. Without `replace`, a supplied value also replaces an existing value. To replace a value with another generated value, use a new name instead ([When no person is present](/cloud/guides/supply-a-secret-value-without-exposing-it/#when-no-person-is-present)).

Call `tzcloud_store_secret` with `replace: true`. Pass `value` only when the person deliberately shared the new value in the conversation. Otherwise, leave `value` out and run the `secret rotate` line it returns ([step 2: Supply the value without exposing it](#2-supply-the-value-without-exposing-it)).

Where the environment's running copy has a binding of the name, the response also has `next`. That is the `tzcloud_restart_application` call you make once the value is written: at once for a value in the call, or once the command ends with status 0. It is a separate call because a copied command cannot by itself make the running copy read a value. A `secret rotate` line run with no grant piped in, under the token this computer signed in with, may take `--restart` to restart in the same call.

So a rotation takes one of two forms:

- **Through MCP, two calls.** Store or rotate the value, either in the tool call or through its returned `secret rotate` command. That step changes only the stored value. After it succeeds, follow the response's `next` and call `tzcloud_restart_application` so the running copy reads the replacement. HTTP API callers can combine the write and restart as described below.
- **On the HTTP API, one call.** A script sending the value with its own token can pass `restart: true` and `wait_seconds` up to 45. The response waits that long and reports the result in `restart`. If the restart is still running, follow `next` to `read_status`. If restart is refused, the replacement value remains stored; follow `next` to call `restart_application` later.

When the new value is used depends on how it reaches the application's code:

- **An upstream's key.** The gateway uses the new value from its next call, with no redeploy.
- **A bound setting.** The running container keeps the previous value until the environment's next deploy or promote, or a `tzcloud_restart_application` where the running copy already has the binding.

#### Check that a rotation reached the running copy

A bound setting takes three calls to check. An upstream's key needs none, because the gateway uses the stored value from its next call.

1. You call `tzcloud_read_status` for the environment. `rotated_since_read` lists each setting whose secret changed after the running copy started.
2. Where the setting is listed, you make the `tzcloud_restart_application` call for that environment, the one the rotation's response gave as `next`.
3. You call `tzcloud_read_status` again. Where the setting is absent from `rotated_since_read`, the running copy has the stored value.

`tzcloud_list_secrets` gives the same reading for one name in one call. Name the application and the environment. Where the name's row lists the setting in `applied_settings` and `restart_needed` is false, the running copy has the stored value.

The row's two fingerprints confirm it from the values themselves. A fingerprint is a short code the platform computes from a value with a key of its own. `fingerprint` is the fingerprint of the value stored now. `applied_fingerprint` is the fingerprint of the value the running copy received when it last started. If the two are equal, the running copy has the stored value. If they differ, it still has the previous one, and `tzcloud_read_status` lists the name in that environment's `settings_mismatch`.

A fingerprint does not reveal the value, and nobody can test a guess against it offline. Only someone allowed to overwrite the live secret could compare a guess. If either side is null, no fingerprint was recorded there, and nothing is compared.

A deploy or a promote also starts a new running copy, which reads the stored value, so either reading applies after one too.

For an upstream key, compare `fingerprint` and `rotated_at` before and after rotation with `tzcloud_list_secrets`, and check that `tzcloud_list_outbound_apis`'s `credential_name` names the key. Make one call through that upstream to a route requiring the key, then read `last_call.at`, `outcome` and the provider's `status`. Success after rotation confirms that the provider accepted the gateway's key, without identifying the value sent. `last_call` covers both environments, so test when you can distinguish your call from other traffic.

If a secret leaks into a chat, a log, a commit, or an email, replace it at the service that issued it, then replace the stored value with `tzcloud_store_secret` and `replace: true`. Deliberately pasting a secret into chat does not itself require rotation. A separate leak still does.

### 4. The platform's own names

Each application scope has three names that belong to the platform:

- `credential-<application id>`, the environment's platform credential;
- `database-<application id>`, the database credential named in the provisioning result; and
- `issue-tracking-<application id>`, the token of the application's [issue-tracking space](/cloud/concepts/glossary/#issue-tracking-space), whose value the platform never shows.

Without `replace: true`, `tzcloud_store_secret` refuses all three names with `platform_minted_name`. A replacement still refuses the issue-tracking token. On the HTTP API, `store_secret` with `replace: true` accepts the other two at the development scope, creates a replacement credential, and returns its value once. Creating that replacement is called a re-mint. The MCP tool refuses this replacement with `local_route_required`.

Run `turnzero provision --application <application id>` with nothing sent to standard input instead. Make any `tzcloud_submit_manifest` call it prints, and run the [provision line](/cloud/concepts/turnzero-command/#running-on-your-machine) that call returns. The command calls `store_secret` with `replace: true` under its grant on the HTTP API, receives each value once, and writes the environment file.

After a development rotation:

- **Database password.** An open PostgreSQL session keeps working; new connections need the new value.
- **Running container.** A running development container holds the previous values until it restarts, so the command's last credential replacement also restarts it. If a development deploy is still in progress, the printed answer directs a restart instead. Call `tzcloud_restart_application` on development once that deploy ends. The redeploy loads the new platform credential and, if your manifest declares a database, its new connection string from the platform's secret store. It does not count toward the day's deploys.
- **Previous platform credential.** The HTTP API refuses it at once. The storage, logging, and egress endpoints accept it for up to the interval [Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/) states.

### 5. List what is stored

`tzcloud_list_secrets` returns one row per stored name and scope. Pass `application` and `environment` to narrow the rows. Each row has `name`, `scope`, `application`, `environment`, `created_at`, `rotated_at`, and `settings`, the settings the manifest binds to the name. An environment row also has `applied_settings`, `restart_needed`, `fingerprint`, and `applied_fingerprint`, as [step 3 (Replace a value)](#check-that-a-rotation-reached-the-running-copy) describes.

Its `consumers` list identifies the environment's sign-in route, push configuration, or an upstream bound to the application that declares this name as its credential. Account-scoped rows list no consumers.

For an upstream key, `applied_fingerprint` is `null` because the running copy receives no setting from that name. This does not mean the rotation failed. The gateway reads the stored key on each forwarded call, as [Secrets](/cloud/backend-packages/secrets/#what-it-provides) explains.

### 6. Delete a value

`tzcloud_delete_secret` deletes one stored value: a key stored under the wrong name or at the wrong scope, or one no longer needed. It takes `name`, `application`, and `environment` as the write actions do.

The call returns a [pending action](/cloud/concepts/glossary/#pending-action) and an approval link, and nothing is deleted until the person approves it in the browser. Give them the approval link. You read the outcome with `read_approval_status` ([The pending action](/cloud/concepts/what-happens-without-asking/#the-pending-action)).

To move a misplaced key, the order depends on where it belongs. Where the key belongs under a new name or at the application's other environment, store it there first and then delete the wrong entry. Where it belongs under the same name at another scope, delete the wrong entry first and store only once `read_approval_status` reads `completed`, because `tzcloud_store_secret` refuses the name `scope_fixed` while the wrong entry exists.

The platform refuses a name something still reads, `secret_in_use`, and the `detail` lists each use:

- a binding in the manifest's `settings`;
- a binding in the running copy of the environment whose scope has the name;
- a binding in a deploy, promote, or redeploy in flight to the environment whose scope has the name;
- an upstream that uses it as its key;
- a sign-in method of the same environment's [realm](/cloud/concepts/glossary/#realm), or that environment's push configuration, that uses it now.

A sign-in method of the application's other environment reads that environment's own value, never this one. When you point a realm's sign-in method at another stored name, the earlier value stays in the [realm vault](/cloud/concepts/glossary/#realm-vault), where nothing reads it. That copy is no use, and the deletion removes it too.

End each use first, then delete the name. To end a binding's use, remove it from the manifest's `settings`, call `tzcloud_submit_manifest`, then deploy or promote each environment whose running copy carries it. To keep a use running, point the upstream, sign-in method, or push configuration at another stored name with `tzcloud_declare_outbound_api`, `tzcloud_configure_app_sign_in`, or `tzcloud_configure_push`.

An upstream the application no longer calls ends with a `tzcloud_declare_outbound_api` call that passes `remove: true` ([End an upstream](/cloud/guides/call-an-external-api-with-an-api-key/#end-an-upstream)). An account-scope name is in use only where an upstream of one of the account's applications uses it as its key. The three names of the platform's own from step 4 (The platform's own names) are refused `platform_minted_name`, because the platform deletes each with its environment, its application, or the connected account.

If a use starts before approval, the pending action ends `declined`, with nothing deleted, because the request no longer matches the approved deletion. If a use starts after approval, the action ends `failed` with `secret_in_use`. If the value is already gone or has been stored or rotated again since approval, the action completes with `deleted: false` and deletes nothing.

The secret store keeps the deleted value for ninety days before it purges it, and no action can read or restore it. To stop a key from working, replace it at the service that issued it.

### Bind a value to a setting

The application uses some values directly, such as a webhook signing secret. Bind each one in the manifest's `settings`, which maps a setting name to the stored name, as the [worked example](#worked-example-a-webhook-signing-secret) shows. Store the value under the same name in each hosted environment.

Unlike an upstream's key, a bound value is in the container, where anything that can read the process's environment can read it. The process's environment also has the platform's own settings, which [A deployed app's settings](/cloud/concepts/the-settings-a-deployed-copy-receives/) lists. [Bind a stored value to a setting](/cloud/guides/author-the-manifest/#bind-a-stored-value-to-a-setting) gives the binding's rules, its refusals, and what a local run reads instead.

A value that is not secret, such as a page title, is not stored at all. It goes in the manifest's `settings` as `{"value": "<text>"}`, the same in every environment ([Set a value that is not secret](/cloud/guides/author-the-manifest/#set-a-value-that-is-not-secret)). A value that is not secret but differs between development and production is stored and bound like a secret, with one value at each environment's scope.

### A key that a sign-in method uses

The work-account route's client secret and Sign in with Apple's signing key are stored like any secret, at the application's scope in the realm's environment, Apple's as its `.p8` file named in `value_file`. `tzcloud_configure_app_sign_in` then takes the name ([Add work-account or Apple sign-in](/cloud/guides/add-work-account-or-apple-sign-in/#1-store-the-client-secret-or-the-signing-key)) and moves the value into the realm vault, where only the accounts service reads it.

The same two names can live in the manifest's `realm` member instead, which names them for each realm the application has ([Configure sign-in and push in the manifest](/cloud/guides/author-the-manifest/#configure-sign-in-and-push-in-the-manifest)). There, a name not stored yet is accepted, and each deploy and promote lists it in `outcome.provider_credentials_missing` until it is stored.

## Expected result

**For the AI tool:** Check these results before reporting success to the person.

For an outside API's key, `tzcloud_list_secrets` lists the name, `tzcloud_declare_outbound_api` returns the declaration, and the backend's call through the gateway returns the API's own response with the header `x-egress-upstream: weather`.

A `tzcloud_store_secret` call with no `value` or `generate` returns `state: awaiting_value` with the command line. Add `replace: true` for a replacement; its response has `next` where a restart applies the new value. Nothing is stored until the command runs. A call naming `generate` instead returns a `secret` object with `stored: true` and `generated`, never the value.

When the command runs, the HTTP `store_secret` response has `secret` with `stored: true` and `resupplied`, true if an existing value was replaced. If a running copy reads the value, `next` names the `restart_application` call. With `replace: true`, `secret` has `rotated: true` instead. Then the response adds `settings` only where the manifest binds the stored name, listing just the settings bound to that name. `restart_environment` names the environment where restarting would apply the replacement. If it names that environment and starts no restart, `next` gives the call.

Each result includes a `detail` that never contains a value you stored. The last sentence of the `detail` names the [worked example](#worked-example-a-webhook-signing-secret) above. Each result also includes `page`, the address of this page. The command prints the result and its `detail`, and nothing of the value, so the command adds no secret value to the conversation.

`tzcloud_list_secrets` then lists the name with its `created_at`, and with a `rotated_at` after a replacement.

Where the manifest binds the name, `tzcloud_submit_manifest` returns one row per setting and environment the application has, showing `stored: true` where the name is stored at that environment's scope. Its `next` lists the `tzcloud_store_secret` call for each name and environment not stored yet, so a name it leaves out is stored. Then each environment's `not_stored` in `tzcloud_read_status` lists any still missing, empty once all are stored. The next deploy or promote injects the value as the setting, and after a rotation a restart gives the running copy the new value. [Check that a rotation reached the running copy](#check-that-a-rotation-reached-the-running-copy) confirms it.

`tzcloud_delete_secret` returns 202 with `pending_action` and `approval_url`. After the person's approval, `read_approval_status` returns `completed` with `deleted: true`, and `tzcloud_list_secrets` no longer lists the name. Where the value was already gone, or changed after the person's approval, the action completes with `deleted: false`.

## Refusals

These tables list the refusals these steps most often meet; the [refusals page](/cloud/reference/refusals/) lists all of the platform's refusals, with the cause and remedy of each. A backend package's own failures are listed on its package page.

**For the AI tool:** Use the remedies below. Where a remedy needs the person, explain the next step to them.

A refusal identifies the action, gives the cause in its `detail`, and writes nothing.

### Names, scopes, and stored values

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `invalid_request` | 400 | A field is invalid, and the `detail` names it. It may be a `name` that breaks the rule in step 1 (Choose the name and the scope), or an empty or too-long `value`. It may be an `environment` other than `development` or `production`, or `generate` named beside a value or with no `application`. Or `value_file` is named beside `value`, or is a path one command line cannot contain, which [Store a value from a file](/cloud/guides/supply-a-secret-value-without-exposing-it/#store-a-value-from-a-file) lists. | Correct the field the `detail` names and send the request again. If the value leaked accidentally or separately from deliberate chat entry, follow [step 3 (Replace a value)](#3-replace-a-value). Deliberate chat entry alone does not require rotation. |
| `no_such_application` | 404 | `application` names no application of the connected account. | Use the identifier `tzcloud_list_applications` returns. |
| `application_other_account` | 403 | `application` names an application that another account holds, not the account the call is signed in as. The `detail` names the account the call acted as and nothing of the other one. | Compare `turnzero whoami` with `read_account` over your MCP connection. Make the call from the one signed in to the account that holds the application. |
| `not_found` | 404 | `tzcloud_store_secret` with `replace: true` or `tzcloud_delete_secret` named a secret not stored at the scope named. An HTTP re-mint can also find no development database. Where the name is stored at the application's other environment alone, `detail` says so. | Name the scope `tzcloud_list_secrets` gives, or store the name at that scope first. For the database credential, declare the database service in the manifest. |
| `scope_fixed` | 409 | The name is already stored at another scope, and it may not move to the scope the request named. The application's other environment is never refused. | Use the scope the refusal's `scope`, `application`, and `environment` members give, or store the value under a new name. |
| `secret_count_limit` | 409 | `tzcloud_store_secret` would add a name to a scope that already holds 100: at an application's environment scope, every name stored there; at the account scope, the names you stored. Nothing was written. | Delete a name no longer needed at that scope with `tzcloud_delete_secret`, then store again. Replacing or rotating a name already stored there is never refused. |

### Platform credentials and values in use

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `platform_minted_name` | 409 | A default `tzcloud_store_secret` call or `tzcloud_delete_secret` named one of the three names in step 4. A replacement named the issue-tracking token or another platform name outside development. | Store your value under your own name. For new development credentials, run `turnzero provision --application <application id>` with nothing piped, then make any call it prints. Its last re-mint restarts a deployed development copy. If a deploy blocks that restart, call `tzcloud_restart_application` on development after it ends. The restart spends no daily deploy. |
| `secret_in_use` | 409 | `tzcloud_delete_secret` gave a name that something still reads: a binding, an upstream, or a realm sign-in method or push configuration of the same environment. The `detail` lists each use. | End each use the `detail` lists, then call `tzcloud_delete_secret` again. Remove a binding, then deploy or promote each environment whose running copy has it. Point an upstream, a sign-in method, or a push configuration at another stored name, or end an upstream the application no longer calls by calling `tzcloud_declare_outbound_api` with `remove: true`. |
| `local_route_required` | 409 | `tzcloud_store_secret` with `replace: true` named a platform credential at the development scope through MCP, which returns no credential value. An MCP call for your own secret is never refused this way: it writes the `value` the person shared, or returns the command line. | Run `turnzero provision --application <application id>` with nothing piped, and make any `tzcloud_submit_manifest` call it prints. Run the line that call returns. It normally restarts a deployed development copy. If a deploy blocks the restart, call `tzcloud_restart_application` on development after that deploy ends. This restart takes the new platform credential and, if your manifest declares a database, its new connection string; it spends no daily deploy. |
| `rotation_in_flight` | 409 | Another HTTP `store_secret` call with `replace: true` for the same development database credential was still running, so nothing was changed. | Wait for that call to finish, then run `turnzero provision --application <application id>` with nothing piped and make any call it prints. Its last re-mint restarts a deployed development copy. If a deploy blocks that restart, call `tzcloud_restart_application` on development after it ends. The restart spends no daily deploy. |
| `plan_quantity_unset` | 409 | An HTTP `store_secret` call with `replace: true` for the development database credential needs the size's connection-limit quantity, which is not set, so nothing was changed. | Wait for platform staff to set it, then run `turnzero provision --application <application id>` with nothing piped and make any call it prints. Its last re-mint restarts a deployed development copy. If a deploy blocks that restart, call `tzcloud_restart_application` on development after it ends. The restart spends no daily deploy. |
| `database_provisioning_failed` | 502 | An HTTP `store_secret` call with `replace: true` found the development database recorded but its database role missing, so nothing was changed. | `tzcloud_delete_environment` naming development deletes the database, with development's data and secrets, on one environment or two. A manifest resubmission then sets it up again with a new database; on two environments, call `tzcloud_create_environment` before it. If that deletion fails, report the refusal and quote the reference in its `detail`. |

### Bindings and upstreams

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `setting_secret_missing` | 409 | A deploy or promote read a binding in the manifest's `settings` whose stored name has no entry at that environment's scope. The `detail` names the setting and the secret, and `next` the `tzcloud_store_secret` call to make. | Store the value with `tzcloud_store_secret` for the application and that environment, then deploy or promote again. Or remove the binding from the manifest's `settings`, resubmit the manifest, and deploy or promote again. |
| `credential_not_in_custody` | 409 | The secret name a declared upstream uses is not stored at the scope the call reached. Where it is stored for the application's other environment alone, `detail` names both environments. | Store the value at that scope with `tzcloud_store_secret`, then retry. If `detail` names the other environment, store the same name at the missing environment's scope, with that environment's value. |

### Store-command grants and sign-in

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `secret_grant_expired` | 403 | The command line ran after its `expires_at`, so nothing was written. | Call `tzcloud_store_secret` again through MCP, with `replace: true` for a replacement, and run the fresh command before its `expires_at`. |
| `secret_grant_spent` | 403 | The command presented a secret grant that was used earlier, so this run wrote nothing. A grant permits one write only. A second run of a command whose write landed is normally refused this way. Where a command's first run is refused this way, someone else used its grant first, and the stored value may not be yours. | Do not run the same command again. `tzcloud_list_secrets` shows when the name was last written. Where it shows no write from your command, call `tzcloud_store_secret` again through MCP, with `replace: true` for a replacement, and run the fresh command. |
| `secret_grant_not_admitted` | 403 | The command was changed to give another name, action, application, or environment than the call that returned it, or a request under its grant asked for a restart or another action or route. Nothing was written, and the grant is not spent. | Run the command exactly as the call returned it. For another name or scope, call `tzcloud_store_secret` through MCP for that name and scope, with `replace: true` for a replacement, and run the command it returns. |
| `authentication_required` | 401 | The request presented no credential, or one that matched no account. For a command line, the `detail` says "The grant this request presented was not accepted": that grant expired and was removed, or the command's secret grant was changed. | For a grant that was not accepted, call `tzcloud_store_secret` again through MCP, with `replace: true` for a replacement, and run the fresh command. Otherwise ask the person to sign in again through the connected client. |

## Related

- [Keep a secret value out of chat](/cloud/guides/supply-a-secret-value-without-exposing-it/) runs the command, from a file, at your own terminal, or with nobody present.
- [Call an external API with an API key](/cloud/guides/call-an-external-api-with-an-api-key/) declares an upstream against the stored name and calls it through the gateway.
- [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/) runs the application under the environment file, with a local value for each bound setting.
- [A deployed app's settings](/cloud/concepts/the-settings-a-deployed-copy-receives/) lists every setting a deployed copy reads, beside the ones you bind.
- [The turnzero command](/cloud/concepts/turnzero-command/) describes `turnzero`, its options, and its exit statuses.
- [Secrets](/cloud/troubleshooting/secrets/) in Troubleshooting starts from what a refused command line prints.
- [Secrets](/cloud/backend-packages/secrets/) states what the secret service provides and what a deletion removes.
- [tzcloud_store_secret](/cloud/reference/actions/store-secret/), [tzcloud_list_secrets](/cloud/reference/actions/list-secrets/), and [tzcloud_delete_secret](/cloud/reference/actions/delete-secret/) in the generated reference give each action's arguments and result.
