Secrets #

View this page as Markdown

On this page

These entries start from what your code or a refusal shows about a value you stored. Store a secret describes the two ways a stored value reaches your application.

Code reads a stored secret from process.env and finds nothing #

Cause. Storing a value does not by itself make it an environment variable. A declared upstream's key stays at the egress gateway, which adds it to each call your code makes to that upstream through the gateway. A value reaches your code as a setting only where the manifest's settings member binds its name, and only from the environment's next deploy or promote.

Check. list_secrets shows a row for the name. Its settings member lists the settings the manifest binds to the name, and is empty where the manifest binds none. The row's applied_settings lists the settings the running copy of your application reads from the name. A setting missing there reaches the running copy at the next deploy or promote. list_outbound_apis returns each upstream's credential_name, which shows whether an upstream uses the name as its key.

A local run's environment file contains the settings listed in Run your app on your computer, step 2 (Read the settings the file holds). It contains no setting bound to a stored secret.

Remedy. For the key of an external application programming interface (API), declare the upstream first (Declare the upstream), then call the API through the gateway. A call to an upstream name not declared is refused 404 undeclared_upstream. For an unchanged software development kit (SDK), declare the upstream with sdk_settings instead, so the SDK reads its base URL and an egress key (An unchanged SDK). For a value your code must read itself, bind it as Bind a value to a setting shows. Store it at each environment's scope of the application, submit the manifest, and deploy again.

A deploy or promote is refused setting_secret_missing #

Cause. The manifest's settings binds a setting to a stored name, and the environment being deployed has no value under that name at its own scope. Each environment reads only its own scope, so a value stored for development is unavailable in production, and the other way round. store_secret stores at production unless the call gives environment development.

Check. The response has status 409, and its error is setting_secret_missing. The detail gives the setting and the stored name, and its next gives the store_secret call to make. list_secrets with the application and the environment shows no row for that name. A submit_manifest response's settings rows show, per setting and environment, whether the name is stored there, and its next lists the store_secret call to make.

Remedy. Store the value with store_secret, giving the application, the environment the deploy goes to, and the name the detail gives, then deploy or promote again. The refusal's next is that call, filled in. Or, where the code no longer reads the setting, remove the binding from the manifest's settings, submit the manifest, and deploy again. Store a secret explains the scopes.

The running copy seems to use the old value after a rotation #

Cause. Rotating a secret changes the value the platform stores. A bound setting reaches the running copy only when a new copy starts: at the next deploy or promote, or at a restart_application where the copy already has the binding. A restart made while a deploy is still in progress is refused. A restart that fails its health check leaves the old copy running.

Check. list_secrets with the application and the environment shows the name's row. Its fingerprint is a short fingerprint the platform makes from the stored value with a key of its own. applied_fingerprint is the matching fingerprint for the value the running copy received when it last started. Neither fingerprint is the value or a hash of it, and neither can be tested offline. Only someone allowed to overwrite the live secret could compare a guess. Where the two fingerprints are equal, the running copy has the stored value. Where they differ, it still has the previous one.

The first four characters of a fingerprint are the id of the key that made it. Two fingerprints can be compared only where those four characters agree. A null fingerprint means none was recorded on that side: the value was stored, or the copy started, before the platform made fingerprints, or the platform did not yet hold its key. read_status lists each name whose two fingerprints differ in the environment's settings_mismatch. Its settings_apply names the action that gives the running copy the stored value.

Remedy. Call restart_application for that environment. Wait with read_status and wait_seconds until the restart's row ends deployed. Then read list_secrets again: the two fingerprints now agree, and settings_mismatch is empty. If settings_mismatch reads not_comparable, the platform's key changed between the two fingerprints. A restart records a fingerprint under the current key and clears the entry. A deploy or promote, if you want one anyway, also starts a new copy and clears it.

A partner's signatures never verify #

Cause. The secret your code checks signatures with was created with store_secret's generate, but the sender issued the value. The platform never returns a created value, so the sender and your code hold different values.

Check. list_secrets lists the name at the scope of the environment that receives the calls. Then check how the value was stored: a call that named generate returned generated and no command line, so the value it stored is not the sender's.

Remedy. Save the sender's value in a file outside your application's folder. Store it under the same name with value_file: call store_secret with replace: true where the name is already stored, or without replace where it is not. Bind the name to the setting your code reads in the manifest's settings, as Receive a signed webhook shows. A running copy that already has the binding reads the new value after the restart_application call the rotation's next gives.

The secret line is refused authentication_required and says the grant was not accepted #

Cause. The command that store_secret returned presented a secret grant the platform no longer has. The grant expired and was removed, or the command was changed, for example cut short when it was copied.

Check. The command printed a refusal with HTTP status 401 and authentication_required, and its explanation opens "The grant this request presented was not accepted". Nothing was written.

Remedy. Ask your AI tool to call store_secret again for a fresh command. Leave value out and keep replace: true for a replacement. Run the command whole, as given, before its expires_at. Signing in again does not help, because the refusal is about the command's secret grant. Keep a secret value out of chat lists each refusal of the command.

The secret line is refused secret_grant_expired #

Cause. The command ran after the expires_at its call returned. A grant lasts fifteen minutes, so a command that waits for you to type a value can run out of time.

Check. The command printed a refusal with status 403 and the error secret_grant_expired. Nothing was written, and a stored value is unchanged.

Remedy. Ask your AI tool to call store_secret again for a fresh command. Leave value out and keep replace: true for a replacement. Run the command before its expires_at. If you type the value yourself, have it ready before your tool makes the call.

The secret line is refused secret_grant_spent #

Cause. The command presented a secret grant that was used earlier, so it wrote nothing. A grant permits one write only. Most often the same command ran twice, and its first run stored the value.

Check. The command printed a refusal with status 403 and the error secret_grant_spent. list_secrets shows when the name was last written, in created_at or rotated_at.

Remedy. Do not run the same command again. If its first run ended with status 0, the value is stored. If the command's first run was refused, or list_secrets shows no write at the time it first ran, another party used the same secret grant, and the stored value may be theirs. Store or rotate a value of your own at once, and treat the command as exposed. Ask your AI tool to call store_secret again for a fresh command. Leave value out and keep replace: true for a replacement. Run the command to replace what is stored under the name.

The secret line is refused secret_grant_not_admitted #

Cause. A grant is for one write: the action, the name, the application, and the environment of the call that returned the command. The command was changed, for example to another --name, or it was used for something else, such as a restart.

Check. The command printed a refusal with status 403 and the error secret_grant_not_admitted. Nothing was written, and the grant is not spent.

Remedy. Run the command exactly as the call returned it, before its expires_at. For another name or scope, ask your AI tool to call store_secret again for that name and scope. Leave value out and keep replace: true for a replacement. Run the command it returns.

The provision line is refused #

Cause. The provision line uses a secret grant to replace the local run's platform credential, and its database credential if the manifest declares a database, once within fifteen minutes. The old values then stop working. A verifier is a random secret the command keeps on this computer. The platform checks it against the challenge the command printed earlier.

secret_grant_spent means an earlier run of the command already used its grant, or someone who read this computer's credential file used it first. secret_grant_expired means the command ran after its expires_at. authentication_required means the platform found no grant matching this computer's verifier and the requested application. The command was changed, for example to give another --application, or ran on another computer.

Check. If the first request was refused, the command's message included "pending verifier" and "nothing was re-minted". That means no grant matched this computer's saved verifier and no credential was replaced. It named the refusal and printed the challenge and call again. The environment file is as it was. Where the refusal came on the second request, the command ended with status 2. It printed "The development database credential was re-minted and its value was not written".

Remedy. Run turnzero provision --application <application id> with nothing piped, and make any call it prints, then run the command that call returns as given. That command re-mints the platform credential, and the database credential where your manifest declares one, so a value someone else received stops working. If a response to a request that named local_run has no provisioning, the platform could not prepare the command; run turnzero provision --application <application id> with nothing piped, and make any call it prints.

A local run is refused or reaches the wrong application though .env is current #

Cause. node --env-file=.env keeps a variable already set in your shell and ignores the file's line for it. With the run line the file wins over the shell, so this happens only where the run was started with node --env-file, as the one-command check in Run your app on your computer does. A TURNZERO_CLOUD_APP_TOKEN or APP_DATABASE_URL exported earlier, for another application or before the provision line last ran, then wins over the value the command wrote. The platform refuses the old credential, or the calls reach the other application's data.

Check. In the shell that starts the run, list the names of the variables the file also sets. These commands print names alone, never a value: env | cut -d= -f1 | grep -E '^(TURNZERO_CLOUD_|APP_)' in a POSIX shell, or (Get-ChildItem Env:TURNZERO_CLOUD_*, Env:APP_*).Name in PowerShell. Any name the list shows is read from the shell, not from .env. Two names it can show are inputs of an unattended provision, and neither is in the file: TURNZERO_CLOUD_MINTED_TOKEN and TURNZERO_CLOUD_ORIGIN. TURNZERO_CLOUD_APPLICATION and TURNZERO_CLOUD_API are in the file, so they cause no harm while the shell has the same values.

Remedy. Clear every name the list shows, except the two inputs of an unattended provision. Also clear TURNZERO_CLOUD_APPLICATION where it gives another application, and TURNZERO_CLOUD_API where it gives a different origin from the one the command was given. TURNZERO_CLOUD_API gives an origin, such as https://turnzero.ai, not an application. Start the run in the same command, since a later command in the same shell can still inherit a cleared name.

In a Unix-style shell, such as bash or zsh: env -u TURNZERO_CLOUD_APP_TOKEN -u APP_DATABASE_URL node --env-file=.env …, one -u flag per stale name the list shows. In PowerShell, as one invocation: Remove-Item Env:TURNZERO_CLOUD_APP_TOKEN, Env:APP_DATABASE_URL -ErrorAction SilentlyContinue; node --env-file=.env ….

A new shell helps only where it is opened outside the tool's own process, not a tab or pane the tool's terminal forks from the current one, which can still inherit an exported name. Run your app on your computer lists the settings the command writes into the file, and PORT, which it does not write.