store_secret #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/store_secret, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_store_secret.
OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).
Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.
Contract description #
Store a secret under a name, or replace it with replace: true. Pass value only if it is already in this chat. Your host may record arguments. Without value or generate, nothing is stored. You get state: awaiting_value and four commands. Run command_npx (command_npx_windows on Windows), or installed command (command_windows), once as given before expires_at. Use value_file to send an on-disk value without reading it into chat.
No tool reads stored values. Replacement needs an existing name and cannot use generate. Apply a replaced bound setting with deploy, promote or restart_application. next gives the restart. Check read_status for rotated_since_read.
For an outside API key, use declare_outbound_api and the gateway. Use sdk_settings for an unchanged SDK. Bind it in manifest settings only if the host is fixed in code your task forbids changing. For that binding, declare no upstream and list its host in manifest egress.
More about this action #
Storing a name again at the same scope replaces its value in place, as store_secret with replace: true does, and read_status lists the setting under rotated_since_read until a restart. Pass value only for a value already in the conversation; for any other value, use the command, here or from store_secret with replace: true, which refuses a name that was never stored.
With application, the optional environment (development or production, and production where you give none) chooses which environment's scope of that application stores the value. One name may exist at both environment scopes of one application, each with its own value, so development can keep a test key and production a live one. Without application, the value goes to the account scope. The egress gateway reads the account scope for both environments, and no binding reads it.
Apart from that, a name stays at the scope where it was first stored. A name at an application's scope cannot be stored at the account scope or at another application's scope. A name at the account scope cannot be stored at an application's scope. Either is refused scope_fixed. Everything other than this call refers to a stored value by its name.
The command pipes a short-lived grant for that one write to the turnzero command. The command reads the value on that machine and sends it to this action's address. It never takes the value from its command line, and prints neither the value nor the grant.
Pass value_file, a file on that machine that contains the value, and the command reads it there, so your tool can run the command itself. Pass none, and the command asks for the value at a terminal, so the account's owner runs the command in a terminal of their own.
The value_file argument: optional, and only on a call that passes no value. It is the path of the file on your machine that contains the value, absolute or relative to the folder the command runs in. The command reads the file, and the platform never reads the path. Without it, the command asks for the value at a terminal prompt. A person can answer that prompt and an AI coding tool cannot, so pass the file on your first call.
Keep the file outside the application's folder, because a deploy zips that folder. Once the command exits with code 0, delete the file, as you would a file containing a provider's API key or a test key. Keep it only while a sender still needs the value, such as a webhook signing secret you made, since no action shows a stored value again.
A path that contains a control character, a double quote, $, a backtick, %, !, &, |, <, >, ^, a typographic double quote, a doubled backslash, or a trailing backslash is refused invalid_request. So is ~, or a path that opens with ~/ or ~\, because no shell expands those in double quotes. So is a value_file passed beside generate, or on a call that carries the value itself.
For a value nobody chooses, such as a session signing secret, pass application and generate. The platform creates 32 random bytes in custody at that scope during the call, and returns the form, never the value.
The generate argument: optional, and only with application. It is base64url_32, 43 base64url characters for most uses, or hex_32, 64 lowercase hexadecimal characters where a library reads a key in hex. Both forms are 32 random bytes. The value is stored at the one environment scope that application and environment give, and no action ever returns it. Passing generate beside value_file, on a call that carries the value itself, or with no application is refused invalid_request.
A name that already exists at that scope is refused secret_exists: a call with generate never replaces a value. To replace a created value, store a new name with generate, bind the setting to it, deploy, and delete the old name with delete_secret. A later store or rotation that carries a value replaces a created value for good.
No tool or person ever reads a created value. So a secret that an outside service must also have, such as a webhook's signing secret, is never generated: store it from that service's value, through value_file or at a terminal.
A stored value reaches your code in one of two ways. The egress gateway applies a value an upstream refers to at its edge, and the value never enters the container; your code calls the gateway to use it. A value the manifest's settings bind is injected into the container as that setting at the environment's next deploy or promote. A restart_application injects it too, where the running copy already has the binding. A store that replaces a value the running copy reads returns next, the restart_application call to make.
A store that would add a name to a scope that already has 100 names is refused secret_count_limit. At an application's environment scope, every name there counts. At the account scope, only the names you stored count.
The value argument: a browser session's call must carry it, or pass generate.
With replace: true, the call replaces a stored secret's value under the same name and scope. Pass value only for a value already in the conversation, since a host may record a tool's arguments in its transcript. A call with no value rotates nothing. It returns state: awaiting_value and four command forms. command_npx sends the new value from this computer; command_npx_windows is its Windows form. command and command_windows use the installed turnzero command. Run it once before expires_at.
A bound setting gets the value at the next deploy or promote, or at a restart_application where the running copy has the binding. Where a running copy reads the name, next gives the restart_application call that applies it. To check that the running copy has it, call read_status: its rotated_since_read lists each setting whose secret changed after the copy started, until the next restart.
The command pipes a short-lived grant for that one write to the turnzero command. The command reads the new value on that machine and sends it to this action's address with replace: true. The write's response lists the settings the value supplies, and the command prints that list on its rotated: line.
The value argument: only for a value the person already put in the conversation, which the transcript already contains. The platform writes it as the HTTP action route does, with the same bounds, and never shows it again. A value on disk, or one only the person knows, goes through the command, which never shows it to the assistant.
Pass value_file, a file on that machine that contains the new value, and your tool can run the command itself. Pass none, and the account's owner runs the command in a terminal of their own, where the command asks for the value.
The value_file argument: optional, and only on a call that passes a name you stored and no value. It is the path of the file on your machine that contains the new value, absolute or relative to the folder the command runs in. The command reads the file, and the platform never reads the path. Without it, the command asks for the value at a terminal prompt. A person can answer that prompt and an AI coding tool cannot, so pass the file on your first call.
Once the command exits with code 0, delete the file, as you would a file containing a provider's API key or a test key. Keep it only while a sender still needs the value, such as a webhook signing secret you made, since no action shows a stored value again.
A path that contains a control character, a double quote, $, a backtick, %, !, &, |, <, >, ^, a typographic double quote, a doubled backslash, or a trailing backslash is refused invalid_request. So is ~, or a path that opens with ~/ or ~\, because no shell expands those in double quotes. So is a value_file on a call that carries the value itself.
The environment argument chooses the application's environment scope, as it does for store_secret.
Nothing that refers to the name changes at a rotation. A value an upstream refers to is used from the gateway's next call. To check that the upstream accepts it, call a route of the application that uses the upstream with request_route, naming the environment the value was rotated in.
The restart is a separate call, restart_application, because the command that writes the value runs under a grant that can do nothing else. A copied line therefore cannot make a running application read a value. Over the HTTP action route, under a bearer credential of your own, a write that passes restart as true starts the restart in the same call. The response's restart member says whether the restart started. Pass wait_seconds, up to 45, beside it, and the response waits until the restart ends and says how it ended.
A replacement creates no value. To replace a value that store_secret created with generate by a new created value, store a new name with generate, bind the setting (environment variable) to it, and delete the old name.
On the development scope alone, a call over the HTTP action route also re-mints the two credentials the platform minted, database-<application id> and credential-<application id>, and returns the new value once. For the database name, the response also gives the connection facts and the application's connection_limit. This tool refuses those two names local_route_required, because it returns no value of a platform-minted credential. On your machine, run turnzero provision --application <id> with nothing piped: it leads to the command that makes the call.
Access and action metadata #
{
"name": "store_secret",
"resource": "secret",
"tier": "reversible",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"clients": [
"bearer",
"browser_session"
],
"summary": "Put a value into custody under a declared name. The value travels as a `POST` to this action's address, or as the tool's `value` only for a value the person already put in the conversation, since a host may record a tool's arguments in its transcript. A call that passes `generate` and an application has the platform create the value in custody and returns none. A call with no `value` and no `generate`, through a tool or on that route under a bearer credential of your own, stores nothing. It returns four command forms. `command_npx` sends the value from this computer under a short-lived grant; `command_npx_windows` is its Windows form. `command` and `command_windows` use the installed turnzero command. The turnzero command reads the value from the file `value_file` gives or at a terminal, never from its command line, and prints neither the value nor the grant. With `replace: true` it replaces a stored value: Replace a named value without a code change. The new value travels as a `POST` to this action's address with `replace: true`, or as the tool's `value`, for a value the person already put in the conversation. A call with a name of your own and no `value`, through a tool or on that route under a bearer credential of your own, rotates nothing. It returns four command forms. `command_npx` sends the new value from this computer under a short-lived grant; `command_npx_windows` is its Windows form. `command` and `command_windows` use the installed turnzero command. Where the running copy of the rotated scope's environment carries a binding of the name, that answer's `next` gives the `restart_application` call to make once the command ends 0. A write carrying `value` under a bearer credential of your own on the HTTP action route and passing `restart` true starts that restart itself, its outcome returned as `restart`, and `wait_seconds`, up to 45, beside it holds that answer until the restart ends. A line's write under its grant, and a browser-session write, never does. The write's answer, which the command prints, gives that environment as `restart_environment`, whose copy keeps the previous value until a `restart_application` of it.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
MCP catalog entry #
{
"name": "store_secret",
"title": "Store secret",
"tier": "reversible",
"scenario": "CHI-L0-08",
"summary": "Store a secret under a name, or replace it with `replace: true`. Pass `value` only if it is already in this chat. Your host may record arguments. Without `value` or `generate`, nothing is stored. You get `state: awaiting_value` and four commands. Run `command_npx` (`command_npx_windows` on Windows), or installed `command` (`command_windows`), once as given before `expires_at`. Use `value_file` to send an on-disk value without reading it into chat.\n\nNo tool reads stored values. Replacement needs an existing name and cannot use `generate`. Apply a replaced bound setting with deploy, promote or `restart_application`. `next` gives the restart. Check `read_status` for `rotated_since_read`.\n\nFor an outside API key, use `declare_outbound_api` and the gateway. Use `sdk_settings` for an unchanged SDK. Bind it in manifest `settings` only if the host is fixed in code your task forbids changing. For that binding, declare no upstream and list its host in manifest `egress`.",
"owners": [
"EGW-L0-03",
"MAN-14",
"SCRT-L0-01",
"SCRT-L0-08",
"SEC-L0-07",
"SEC-L0-20",
"SEC-L0-21",
"SCRT-L0-05"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["name"] |
| / |
The name to store under; it keeps the scope it was first stored with, though it may exist at both environment scopes of one application, and another scope is refused scope_fixed.Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$ |
| / |
The secret value, sent once and never read back. Through the MCP tool, pass it only for a value the person already put in the conversation, since a value on disk goes through the command, which never shows it to the assistant. Type: string Minimum length: 1 Maximum length: 20000 |
| / |
On a call with no value, the local file holding the secret. Keep it outside the application's folder; delete it after the command exits 0 unless a sender needs it. Pass it because a tool cannot type into the command's prompt. ~ or a path the pattern refuses is refused invalid_request.Type: string Minimum length: 1 Maximum length: 1024 Pattern: ^(?:[^"$`%!&\|<>^\u201c-\u201e\u0000-\u001f\u007f\\]|\\[^"$`%!&\|<>^\u201c-\u201e\u0000-\u001f\u007f\\])+$ |
| / |
The platform creates the value, one nobody chooses, such as a session signing secret. A value a sender must also hold, such as a webhook's signing secret, is never generated. A stored name refuses secret_exists; beside value_file or a value, or without application, invalid_request.Type: string Allowed values: ["base64url_32","hex_32"] |
| / |
An application id, to hold the secret at that application's scope; omitted, the secret is held at the account scope. Type: string |
| / |
With application, the environment whose scope of that application holds the secret; absent, production. Refused if given without application.Type: string Pattern: ^(development|production)$ |
| / |
true replaces the value of a name already in custody at this scope, and refuses a name that was never stored. generate is refused with it.Type: boolean |
| / |
The HTTP action route's alone: the tool declares none, and a tool call's answer gives the restart_application call as next to make once the command ends 0, where a running copy binds the name. There, true on a write carrying the value under a bearer credential of your own starts the platform's redeploy of the environment the answer gives as restart_environment. A call there with no value, or under a browser session, restarts nothing, and the answer's restart gives the call to make. The rotation remains whatever the restart's outcome, which the answer's restart gives. Refused invalid_request where it is not a boolean or the call re-mints a platform-minted name over the wire, and secret_grant_not_admitted first under a grant.Type: boolean HTTP action route only, never an MCP tool argument: true |
| / |
The HTTP action route's alone, beside restart true: the seconds, counted from the call's arrival, the answer is held until the restart it started ends, as restart_application's wait_seconds holds its answer. The answer's restart then gives the restart's end state and outcome, or next, the read_status call, where it had not ended. Without restart true, outside 1 to 45, or not an integer, it is refused invalid_request before any write, and secret_grant_not_admitted first under a grant.Type: integer Minimum: 1 Maximum: 45 HTTP action route only, never an MCP tool argument: true |
| / |
The HTTP action route's alone, under a provision grant: the verifier the turnzero command kept, which a grant bound to a challenge requires and an unbound grant ignores. Refused under any other credential.Type: string HTTP action route only, never an MCP tool argument: true |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","secret"] |
| / |
Required value: 1 |
| / |
The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
Type: object Required fields: ["name","scope"] |
| / |
Type: string |
| / |
Type: string |
| / |
True on the answer to a call that carried a value or passed generate: the value is in custody. False with the state awaiting_value, where nothing is stored until the returned command runs.Type: boolean |
| / |
Type: boolean |
| / |
Present where the call passed generate: the form the platform created the value in. The value itself is never returned.Type: string Allowed values: ["base64url_32","hex_32"] |
| / |
Type: ["string","null"] |
| / |
The environment of the application scope that holds the value; null at the account scope. Type: ["string","null"] |
| / |
True where this name feeds a setting a running copy of the scope's environment reads, so the value now stored reaches that copy only at its next deploy, promote, or restart, as list_secrets says of the name. False otherwise, at the account scope and for an unbound name among them. Left out where that running copy's row could not be read after the write.Type: boolean |
| / |
True on the answer to a call that rotated the value. False with the state awaiting_value, where nothing is rotated until the returned command runs.Type: boolean |
| / |
Present only on the answer to a call with no value and no generate: awaiting_value. The call stored nothing and minted a short-lived grant for the one write the returned command makes.Type: string Pattern: ^awaiting_value$ |
| / |
Present with the state awaiting_value: when the grant in the command stops serving, as an ISO 8601 instant. A command run after it is refused secret_grant_expired, or authentication_required once the platform has removed the grant's record, and a new call with no value returns a new one.Type: string |
| / |
Present with the state awaiting_value: one line, for macOS and Linux. It reads echo <grant> | turnzero secret store --name <name>, then --application <application id> --environment <environment> where the call passed an application, and --origin <origin> where the origin that responded is not https://turnzero.ai. It ends with --value-file "<value_file>", or with --value-prompt where the call passed no value_file. Run it once, as given, from the folder a relative value_file is relative to. The turnzero command reads the grant on its standard input, reads the value from the file or at the terminal, and sends it once. It ends 0 where the value was written, 2 where that is unknown, and 3 where nothing was written. Its write normally spends the grant where it lands, and a second write after that is then normally refused secret_grant_spent. A write with another name or scope is refused secret_grant_not_admitted.Type: string |
| / |
Present with command: the same line for every Windows shell, with turnzero.cmd where its head says turnzero. It runs as written in Windows PowerShell 5.1, PowerShell 7, and cmd. On Windows, run this one in command's place, once, as given. The four line members are one command line, so a run of any whose write lands normally spends the grant.Type: string |
| / |
With the state awaiting_value: the same line run through npx, npx --no-update-notifier -y turnzero@<tag> in place of turnzero, the tag latest on production's platform and next on every other. It is present exactly where command is. Run this line first, or command_npx_windows on Windows; it runs whether or not the command is installed. If npx can't run, use command where turnzero --version responds; else give the person the line to run. For a value on disk, value_file makes that line read the file on the machine where it runs. Run npm install -g turnzero@<tag> only if the person wants to keep it. If your tool's permissions blocked the command, tell the person which route you took. A person or a job may run any of the four forms.Type: string |
| / |
With the state awaiting_value: command_npx's line for every Windows shell, with npx.cmd where its head says npx.Type: string |
| / |
Present where a tool call wrote a replacement and carried restart or wait_seconds, which run on the HTTP action route alone. It says that no restart was started and, where next is given, to make that restart_application call.Type: string |
| / |
Present where the call replaced a value at an application scope and restart_needed is true: the exact restart_application call to make, since the running copy keeps the previous value until it restarts. Left out with restart_needed.Type: object Required fields: ["action","arguments"] Additional properties: false |
| / |
Required value: restart_application |
| / |
Type: object Required fields: ["application","environment"] Additional properties: false |
| / |
Type: string |
| / |
Type: string Pattern: ^(development|production)$ |
| / |
Type: string |
| / |
$ref: #/shapes/page |
| / |
Present exactly when a platform-minted name was re-minted on the development scope: the new value, returned once and never read back. Type: string |
| / |
Present on the wire surface when the re-minted name is the development database credential database-<application id>: the development database's connection facts in the shape submit_manifest returns them, and the application's connection_limit beside them. From this answer alone a script composes APP_DATABASE_URL, with the password in value, and writes APP_DATABASE_CONNECTION_LIMIT. Never returned on the MCP surface, which refuses the re-mint local_route_required.Type: object Required fields: ["host","dbName","roleName","connection_setting","connection_limit"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Required value: APP_DATABASE_URL |
| / |
the application's served database-connection-limit quantity, read from its size's row, read at the call: the connections each process holds open at once, the client pool's maximum, never the role's limit of twice it. The local run's line writes it as APP_DATABASE_CONNECTION_LIMIT, the setting a deploy, a promote, and a restart inject.Type: integer Minimum: 0 |
| / |
Present where the application's manifest binds the rotated name to settings: the settings it feeds. The new value reaches the container at the environment's next deploy or promote, and at a restart_application for a setting the running copy already carries; the running container keeps the previous value until then.Type: array |
| / |
Type: string |
| / |
Present where the serving row of the one environment whose application scope the rotation wrote binds the name: that environment, whose running copy keeps the previous value until a restart_application of it applies the new one. The other environment is never given. Absent at the account scope, which no binding reads, and where only an act in flight binds the name, since a restart is refused while it runs; read_status's rotated_since_read covers such a row once it ends.Allowed values: ["development","production"] |
| / |
Present where a call on the HTTP action route passed restart true, and on a re-mint of the development platform credential while development is deployed or a deploy of it is in flight, which restarts the deployed copy. A tool call declares no restart, and its answer gives the call to make as next alone. It gives the restart a write under a bearer credential, or that re-mint, started for environment, the environment restart_environment holds or development. On the preparing form and a browser-session write, it gives the call to make, where an environment is given. Except on the platform credential's re-mint, environment is null where no running copy of the rotated scope carries a binding of the name. With the request's wait_seconds, the answer is held until the restart ends; otherwise its end is read through read_status with wait_seconds.Type: object Required fields: ["environment","started"] Additional properties: false |
| / |
Type: ["string","null"] Allowed values: ["development","production",null] |
| / |
Type: boolean |
| / |
Where the restart started: the version the redeploy re-creates. Type: integer |
| / |
Where the restart was refused by name: the refusal's name, as restart_application gives it. Absent where the platform could not start it.Type: string |
| / |
Where the restart started and the request's wait_seconds saw its row end: deployed or failed.Type: string Pattern: ^(deployed|failed)$ |
| / |
Where the restart started and the request carried wait_seconds: true where the read after the wait found the restart's row ended, false where it was still running or could not be read, which is not a failure.Type: boolean |
| / |
Where the request carried wait_seconds and the restart started: the milliseconds the answer was held after the row started.Type: integer Minimum: 0 |
| / |
Where the wait settled: the restart row's outcome as list_versions returns it, its result succeeded on a deployed row.Type: object |
| / |
Where an environment is given and no restart started: the restart_application call that applies the new value, made from your tool or under a bearer credential. Where the restart started and the request's wait_seconds did not see it end: the read_status call, with wait_seconds 45, that reads it to its end. |
| / |
Type: object Required fields: ["action","arguments"] Additional properties: false |
| / |
Required value: restart_application |
| / |
Type: object Required fields: ["application","environment"] Additional properties: false |
| / |
Type: string |
| / |
Type: string Pattern: ^(development|production)$ |
| / |
Type: object Required fields: ["action","arguments"] Additional properties: false |
| / |
Required value: read_status |
| / |
Type: object Required fields: ["application","environment","wait_seconds"] Additional properties: false |
| / |
Type: string |
| / |
Allowed values: ["development","production"] |
| / |
Required value: 45 |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
"description": "The name to store under; it keeps the scope it was first stored with, though it may exist at both environment scopes of one application, and another scope is refused `scope_fixed`."
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 20000,
"description": "The secret value, sent once and never read back. Through the MCP tool, pass it only for a value the person already put in the conversation, since a value on disk goes through the command, which never shows it to the assistant."
},
"value_file": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^(?:[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\]|\\\\[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\])+$",
"description": "On a call with no value, the local file holding the secret. Keep it outside the application's folder; delete it after the command exits 0 unless a sender needs it. Pass it because a tool cannot type into the command's prompt. `~` or a path the pattern refuses is refused `invalid_request`."
},
"generate": {
"type": "string",
"enum": [
"base64url_32",
"hex_32"
],
"description": "The platform creates the value, one nobody chooses, such as a session signing secret. A value a sender must also hold, such as a webhook's signing secret, is never generated. A stored name refuses `secret_exists`; beside `value_file` or a value, or without `application`, `invalid_request`."
},
"application": {
"type": "string",
"description": "An application id, to hold the secret at that application's scope; omitted, the secret is held at the account scope."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "With `application`, the environment whose scope of that application holds the secret; absent, `production`. Refused if given without `application`."
},
"replace": {
"type": "boolean",
"description": "`true` replaces the value of a name already in custody at this scope, and refuses a name that was never stored. `generate` is refused with it."
},
"restart": {
"type": "boolean",
"x-wire-only": true,
"description": "The HTTP action route's alone: the tool declares none, and a tool call's answer gives the `restart_application` call as `next` to make once the command ends 0, where a running copy binds the name. There, true on a write carrying the value under a bearer credential of your own starts the platform's redeploy of the environment the answer gives as `restart_environment`. A call there with no value, or under a browser session, restarts nothing, and the answer's `restart` gives the call to make. The rotation remains whatever the restart's outcome, which the answer's `restart` gives. Refused `invalid_request` where it is not a boolean or the call re-mints a platform-minted name over the wire, and `secret_grant_not_admitted` first under a grant."
},
"wait_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 45,
"x-wire-only": true,
"description": "The HTTP action route's alone, beside `restart` true: the seconds, counted from the call's arrival, the answer is held until the restart it started ends, as `restart_application`'s `wait_seconds` holds its answer. The answer's `restart` then gives the restart's end state and outcome, or `next`, the `read_status` call, where it had not ended. Without `restart` true, outside 1 to 45, or not an integer, it is refused `invalid_request` before any write, and `secret_grant_not_admitted` first under a grant."
},
"code_verifier": {
"type": "string",
"x-wire-only": true,
"description": "The HTTP action route's alone, under a `provision` grant: the verifier the turnzero command kept, which a grant bound to a challenge requires and an unbound grant ignores. Refused under any other credential."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"secret"
],
"properties": {
"contract_version": {
"const": 1
},
"reference": {
"type": "string",
"pattern": "^[0-9a-f]{10}$",
"description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
},
"secret": {
"type": "object",
"required": [
"name",
"scope"
],
"properties": {
"name": {
"type": "string"
},
"scope": {
"type": "string"
},
"stored": {
"type": "boolean",
"description": "True on the answer to a call that carried a value or passed `generate`: the value is in custody. False with the state `awaiting_value`, where nothing is stored until the returned command runs."
},
"resupplied": {
"type": "boolean"
},
"generated": {
"type": "string",
"enum": [
"base64url_32",
"hex_32"
],
"description": "Present where the call passed `generate`: the form the platform created the value in. The value itself is never returned."
},
"application": {
"type": [
"string",
"null"
]
},
"environment": {
"type": [
"string",
"null"
],
"description": "The environment of the application scope that holds the value; null at the account scope."
},
"restart_needed": {
"type": "boolean",
"description": "True where this name feeds a setting a running copy of the scope's environment reads, so the value now stored reaches that copy only at its next deploy, promote, or restart, as `list_secrets` says of the name (MAN-14). False otherwise, at the account scope and for an unbound name among them. Left out where that running copy's row could not be read after the write."
},
"rotated": {
"type": "boolean",
"description": "True on the answer to a call that rotated the value. False with the state `awaiting_value`, where nothing is rotated until the returned command runs."
}
}
},
"state": {
"type": "string",
"pattern": "^awaiting_value$",
"description": "Present only on the answer to a call with no `value` and no `generate`: `awaiting_value`. The call stored nothing and minted a short-lived grant for the one write the returned command makes."
},
"expires_at": {
"type": "string",
"description": "Present with the state `awaiting_value`: when the grant in the command stops serving, as an ISO 8601 instant. A command run after it is refused `secret_grant_expired`, or `authentication_required` once the platform has removed the grant's record, and a new call with no `value` returns a new one."
},
"command": {
"type": "string",
"description": "Present with the state `awaiting_value`: one line, for macOS and Linux. It reads `echo <grant> | turnzero secret store --name <name>`, then `--application <application id> --environment <environment>` where the call passed an application, and `--origin <origin>` where the origin that responded is not `https://turnzero.ai`. It ends with `--value-file \"<value_file>\"`, or with `--value-prompt` where the call passed no `value_file`. Run it once, as given, from the folder a relative `value_file` is relative to. The turnzero command reads the grant on its standard input, reads the value from the file or at the terminal, and sends it once. It ends 0 where the value was written, 2 where that is unknown, and 3 where nothing was written. Its write normally spends the grant where it lands, and a second write after that is then normally refused `secret_grant_spent`. A write with another name or scope is refused `secret_grant_not_admitted`."
},
"command_windows": {
"type": "string",
"description": "Present with `command`: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`. It runs as written in Windows PowerShell 5.1, PowerShell 7, and cmd. On Windows, run this one in `command`'s place, once, as given. The four line members are one command line, so a run of any whose write lands normally spends the grant."
},
"command_npx": {
"type": "string",
"description": "With the state `awaiting_value`: the same line run through npx, `npx --no-update-notifier -y turnzero@<tag>` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other. It is present exactly where `command` is. Run this line first, or `command_npx_windows` on Windows; it runs whether or not the command is installed. If npx can't run, use `command` where `turnzero --version` responds; else give the person the line to run. For a value on disk, `value_file` makes that line read the file on the machine where it runs. Run `npm install -g turnzero@<tag>` only if the person wants to keep it. If your tool's permissions blocked the command, tell the person which route you took. A person or a job may run any of the four forms (PLD-L0-94)."
},
"command_npx_windows": {
"type": "string",
"description": "With the state `awaiting_value`: `command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx` (PLD-L0-94)."
},
"note": {
"type": "string",
"description": "Present where a tool call wrote a replacement and carried `restart` or `wait_seconds`, which run on the HTTP action route alone. It says that no restart was started and, where `next` is given, to make that `restart_application` call."
},
"next": {
"type": "object",
"required": [
"action",
"arguments"
],
"properties": {
"action": {
"const": "restart_application"
},
"arguments": {
"type": "object",
"required": [
"application",
"environment"
],
"properties": {
"application": {
"type": "string"
},
"environment": {
"type": "string",
"pattern": "^(development|production)$"
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"description": "Present where the call replaced a value at an application scope and `restart_needed` is true: the exact `restart_application` call to make, since the running copy keeps the previous value until it restarts (MAN-14; PLD-L0-84). Left out with `restart_needed`."
},
"detail": {
"type": "string"
},
"page": {
"$ref": "#/shapes/page"
},
"value": {
"type": "string",
"description": "Present exactly when a platform-minted name was re-minted on the development scope: the new value, returned once and never read back (SEC-L0-07; DBS-L0-02)."
},
"development_database": {
"type": "object",
"description": "Present on the wire surface when the re-minted name is the development database credential `database-<application id>`: the development database's connection facts in the shape `submit_manifest` returns them, and the application's `connection_limit` beside them (DBS-L0-02; DBS-L0-04). From this answer alone a script composes `APP_DATABASE_URL`, with the password in `value`, and writes `APP_DATABASE_CONNECTION_LIMIT`. Never returned on the MCP surface, which refuses the re-mint `local_route_required` (SEC-L0-07).",
"required": [
"host",
"dbName",
"roleName",
"connection_setting",
"connection_limit"
],
"properties": {
"host": {
"type": "string"
},
"dbName": {
"type": "string"
},
"roleName": {
"type": "string"
},
"connection_setting": {
"const": "APP_DATABASE_URL"
},
"connection_limit": {
"type": "integer",
"minimum": 0,
"description": "the application's served `database-connection-limit` quantity, read from its size's row, read at the call: the connections each process holds open at once, the client pool's maximum, never the role's limit of twice it. The local run's line writes it as `APP_DATABASE_CONNECTION_LIMIT`, the setting a deploy, a promote, and a restart inject (DBS-L0-04; PLD-L0-63)."
}
}
},
"settings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present where the application's manifest binds the rotated name to settings: the settings it feeds. The new value reaches the container at the environment's next deploy or promote, and at a `restart_application` for a setting the running copy already carries; the running container keeps the previous value until then (MAN-14; SCRT-L0-05)."
},
"restart_environment": {
"enum": [
"development",
"production"
],
"description": "Present where the serving row of the one environment whose application scope the rotation wrote binds the name: that environment, whose running copy keeps the previous value until a `restart_application` of it applies the new one (MAN-14; PLD-L0-84). The other environment is never given. Absent at the account scope, which no binding reads, and where only an act in flight binds the name, since a restart is refused while it runs; `read_status`'s `rotated_since_read` covers such a row once it ends."
},
"restart": {
"type": "object",
"required": [
"environment",
"started"
],
"properties": {
"environment": {
"type": [
"string",
"null"
],
"enum": [
"development",
"production",
null
]
},
"started": {
"type": "boolean"
},
"version": {
"type": "integer",
"description": "Where the restart started: the version the redeploy re-creates."
},
"error": {
"type": "string",
"description": "Where the restart was refused by name: the refusal's name, as `restart_application` gives it. Absent where the platform could not start it."
},
"state": {
"type": "string",
"pattern": "^(deployed|failed)$",
"description": "Where the restart started and the request's `wait_seconds` saw its row end: `deployed` or `failed`."
},
"settled": {
"type": "boolean",
"description": "Where the restart started and the request carried `wait_seconds`: true where the read after the wait found the restart's row ended, false where it was still running or could not be read, which is not a failure (MAPI-04; PLD-L0-84)."
},
"waited_ms": {
"type": "integer",
"minimum": 0,
"description": "Where the request carried `wait_seconds` and the restart started: the milliseconds the answer was held after the row started."
},
"outcome": {
"type": "object",
"description": "Where the wait settled: the restart row's `outcome` as `list_versions` returns it, its `result` `succeeded` on a deployed row (PLD-L0-63)."
},
"next": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"arguments"
],
"properties": {
"action": {
"const": "restart_application"
},
"arguments": {
"type": "object",
"required": [
"application",
"environment"
],
"properties": {
"application": {
"type": "string"
},
"environment": {
"type": "string",
"pattern": "^(development|production)$"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"arguments"
],
"properties": {
"action": {
"const": "read_status"
},
"arguments": {
"type": "object",
"required": [
"application",
"environment",
"wait_seconds"
],
"properties": {
"application": {
"type": "string"
},
"environment": {
"enum": [
"development",
"production"
]
},
"wait_seconds": {
"const": 45
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
],
"description": "Where an environment is given and no restart started: the `restart_application` call that applies the new value, made from your tool or under a bearer credential. Where the restart started and the request's `wait_seconds` did not see it end: the `read_status` call, with `wait_seconds` 45, that reads it to its end."
}
},
"additionalProperties": false,
"description": "Present where a call on the HTTP action route passed `restart` true, and on a re-mint of the development platform credential while development is deployed or a deploy of it is in flight, which restarts the deployed copy (PLD-L0-84). A tool call declares no `restart`, and its answer gives the call to make as `next` alone. It gives the restart a write under a bearer credential, or that re-mint, started for `environment`, the environment `restart_environment` holds or development. On the preparing form and a browser-session write, it gives the call to make, where an environment is given. Except on the platform credential's re-mint, `environment` is null where no running copy of the rotated scope carries a binding of the name. With the request's `wait_seconds`, the answer is held until the restart ends; otherwise its end is read through `read_status` with `wait_seconds` (MAN-14; PLD-L0-84)."
}
}
}
}
Shared contracts #
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md