Store a secret #

View this page as Markdown

On this page

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. 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.
  • Bind it only if its host is fixed in code the task forbids changing; add egress.

For a value the code uses itself, such as a webhook signing secret, bind it.

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. 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, 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.
  • 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).
  • After a rotation, confirms that the running copy has the new value (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.

  • Check that your Cloud connection is signed in (Connect your AI assistant).
  • tzcloud_list_applications returns the application's identifier.
  • Check for Node.js 24 or later and npm, which run the returned npx command (Prerequisites).

Steps #

For failures, see Refusals or Secrets.

Each stored name has one use. A declared upstream's key stays at the egress gateway, which adds it to the application's calls to that API. A value the manifest's settings bind enters the application's container as that 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 before choosing an upstream or binding.

For API keys, read Store an API key and call through the gateway. For other values, read 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).

  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).
{
  "name": "WEATHER_API_KEY",
  "application": "<application id>",
  "environment": "production",
  "value_file": "../secrets/weather-api-key.txt"
}
  1. Declare. You declare the upstream with tzcloud_declare_outbound_api, the stored name as its credential_name, as Declare the upstream shows.
  2. Call. The backend calls the upstream's route on the gateway, which adds the key, as 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).

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). 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 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 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 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, while the stored key stays at the gateway (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 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, 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 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 describes.

"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, 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 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 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. 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 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).

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

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

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, 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, 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). 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 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 lists. 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). 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) 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). 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 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 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 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 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). 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.