mint_token #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/mint_token, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool mint_token.
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 #
Mint an API token for turnzero or a CI job.
A person's signed-in connection is required. A connection presenting an account-wide minted token is refused session_credential_required.
The first command runs on the target computer: turnzero authorize, turnzero token request or turnzero tzmesh register. It prints code_challenge. completion is passed only where that command prints it. awaiting_command returns a completing line, without a token value.
That line runs once, unchanged, on the same computer before expires_at. A token claim line carries a one-time credential. Only the owner runs it, outside AI tools. Authorization and tzMesh registration run in the signed-in AI tool's shell. After authorization, you tell the owner the token's label, expiry and that revoke_token ends it. Token values stay out of the conversation.
More about this action #
Choose the token's scope when you mint it. Use account scope for the whole account or application scope for one application. Ask only for grants your signed-in session may give. A token keeps its scope and cannot mint another token. Call mint_token through a person's signed-in connection, including an AI coding tool connected under that sign-in. An application-bounded token gets token_scope_refused first. An account-wide minted token gets session_credential_required. If the token you have already covers the task, use it. For a deploy or check, set TURNZERO_CLOUD_MINTED_TOKEN from where you keep the token. Keep its value out of the command line. Set TURNZERO_CLOUD_ORIGIN for another estate, then run the deploy or check line. If the token lacks the scope the task needs, use a token that covers it or a person's signed-in connection. If you need to mint a new token, call mint_token from a person's signed-in connection.
Start on the computer where the returned line will run. Use turnzero authorize to authorize that computer, turnzero token request for a token the owner will claim, or turnzero tzmesh register to register an agent. For turnzero authorize and turnzero token request, match the first command's --origin to your signed-in tool connection. When you omit --origin, the command uses TURNZERO_CLOUD_ORIGIN if set, otherwise https://turnzero.ai. For development, use --origin https://dev.turnzero.ai or set the variable to that address.
For turnzero tzmesh register, --origin selects the platform for secret storage when you use --secret. With --to-file, the secret goes to the local file. In either case, --tzmesh-estate selects the estate that mints the token and registers the agent. If you omit --tzmesh-estate, it defaults to the estate selected by --origin, then TURNZERO_CLOUD_ORIGIN if set, then production. Match the mint estate to your signed-in tool connection. Pass the printed code_challenge and the other members the command gives you. Pass completion: mint only if the command prints it. The command keeps its verifier. The HTTP exchange uses code_verifier or mint, which are absent from the MCP tool.
state: awaiting_command means you have one line in four forms and the exchange still needs to run. Use command_npx, or command_npx_windows on Windows. If npx cannot run, use command or command_windows with the installed command. With authorized_computer: true, the line runs turnzero authorize --mint <id>. With completion: mint for the tzmesh grant alone, it runs turnzero tzmesh register --mint <id>. These held lines carry a mint id without a credential. A token claim line carries a one-time code. Run the form once, exactly as returned, where the challenge was printed; paste it nowhere else.
Run the line before the response's expires_at. The exchange deadline is at most five minutes after minting and can be sooner. The turnzero command's first request can stay pending for ten minutes. Ask the owner to run token claim promptly, before expires_at. token.expires_at is the expiry of the token the exchange will mint. If token.expires_at is null, the token has no scheduled expiry. The token record has no token value.
If the exchange returns token_code_refused, the code or held mint could not be used and no token was minted by that exchange. The same refusal covers an unknown, expired or spent code, a verifier mismatch, a suspended account and an ended minting session. For the turnzero commands, make a fresh mint_token call using the same challenge while the first request is still pending. Check the command's “pending until” time. Repeating the first act with the same options during that window prints the same challenge. After the request expires, run the first act again and use the new challenge. Use a fresh person's sign-in if the minting session ended. If the account is suspended, stop and tell the owner to resolve the suspension.
If the command says it is presenting another origin's request at the returned line's origin, let that exchange finish. If it refuses the exchange, follow the command's instruction to call mint_token again with the challenge the indicated first act prints. If it says nothing was sent because there was no pending request, run the indicated first act on that computer with the matching --origin, then mint using its challenge.
With authorized_computer true, the token belongs to that computer. It is account-scoped and marked authorized_computer in list_tokens. It lasts 30 days where expires_in_days is absent, and a longer expires_in_days is refused. Its command runs authorize. Your shell tool runs that command itself, since the account's owner signed you in, or the owner runs turnzero login themselves. Either way, the token is kept in that computer's credential file. The command prints authorized: with the label and expiry when it keeps the token. If you set a shorter lifetime, report the expiry the command printed in place of the default below. After authorizing, tell the owner the token's label and its 30-day expiry, that list_tokens shows it, and that revoke_token ends it.
Start turnzero tzmesh register with --name <name>. Give exactly one destination. Use --secret <secret name> for the secret store or --to-file <file> for a local file. With --secret, use --application <application id> for application scope or omit it for account scope. Use --environment <environment> only with --application.
The command uses this computer's token for the mint estate and, with --secret, for the secret store's estate. If either token is missing, follow the printed sign-in route on that computer. Leave TURNZERO_CLOUD_MINTED_TOKEN unset for tzmesh register.
A mint whose grants are ["tzmesh"] alone may pass completion too, where the command's tzmesh register printed it beside its challenge. That tzmesh mint's command is turnzero tzmesh register --mint <id>, which has no code. On the computer that printed the challenge, use your shell tool to run that tzmesh register line once. Put the options from the first act after the line. Check the final command status and its output. registered: identifies the agent and its id. Confirm the command also reports that it kept the secret at the requested destination. Report the handle or id and where the secret was kept. Keep its value out of the conversation.
For a token claim line, the account owner runs it once, on the computer and as the user that ran turnzero token request, in a terminal outside any AI tool. Show the account owner one returned token claim line in this conversation so they can copy it into their terminal. They can pipe standard output directly into their secret store's command. Never run that line in your shell tool or ask the owner for the token value. If standard error is not a terminal, token claim stops before reading input or sending a request. That stop leaves the code available until it expires. The owner can run the same line once from their terminal if it is still valid.
When tzTeam's connect printed the challenge, use its own completing line in that checkout. Copy the one-time code from between echo and | into the placeholder in the completing line connect printed. Run that line once yourself. Keep the code in that exchange and leave it out of chat and reports.
If npx is blocked and the command is installed, use the returned installed form for your shell. If you still cannot run the authorize line and your task is a deploy, use tzcloud_deploy_files within its limits. For a larger folder you can zip and upload, use tzcloud_mint_upload_grant and then tzcloud_deploy with the uploaded zip as the artifact. Tell the owner which route you took and why. When neither route serves, give the owner the exact authorize line to run once in their terminal on the original computer.
If you cannot run the tzmesh register line, give the owner that exact line with the printed options after it, to run once in their terminal on the original computer. Check the request and exchange deadlines before handing either line over.
The list_tokens action shows tokens without their values, and revoke_token ends one.
The grants argument: Extra grants to carry, from destructive, super_admin, synthetic_seed_purge, synthetic_estate, publication, feedback_queue, issues, tzmesh, tztrack, and test_end_users. Only a session with super_admin gives synthetic_seed_purge, synthetic_estate, publication, and feedback_queue; any session of the account gives issues with space, level, and label, and tzmesh or tztrack, where the account has that product profile, with label. The tzmesh grant takes no level: its token is minted at admin, a mark that bounds no tzmesh call. The tztrack grant takes none either, its token minted at admin, a mark that bounds no tztrack call; either token lives at most 180 days, 180 where expires_in_days is absent. At most one of the seven narrow grants rides a token without super_admin. An application-scoped token takes neither super_admin nor a narrow grant, and asking for one there is refused grant_scope_refused.
Any signed-in session of the account can mint an account token or application token with test_end_users, without changing that token's account or application scope. A minted token needs this grant for test end user actions on production or under a workforce audience. It rides beside destructive, and beside super_admin on an account token, never beside a narrow grant or on an authorized_computer mint. Its token lives at most 180 days, 180 where expires_in_days is absent.
The label argument: A label for the token, 1 to 120 characters, shown by list_tokens. It is required with the issues grant, to identify the token's holder. With that grant it must use printable characters and differ from the label of every unrevoked token for the same space. Required with the tzmesh grant too, identifying the holder, in printable characters; a tzmesh label may repeat. Required with the tztrack grant the same way; a tztrack label may repeat. Required with the test_end_users grant too, in printable characters, and unlike every unrevoked test_end_users label in its scope.
The code_challenge argument is required. It is the S256 challenge of the verifier the command keeps, in 43 base64url characters. Use the value from the first act on the target computer. turnzero login instead passes its challenge in the computer login page's address. On HTTP, a missing or malformed challenge gets invalid_request. Over MCP, input validation rejects a missing challenge before the call reaches the handler. Neither case mints a token.
The authorized_computer argument: When the account's owner runs turnzero login, the computer login page makes this same mint under their own sign-in. Set it true here to authorize the computer that printed the challenge, then tell the account's owner you did.
The completion argument: Optional, its one value mint. With authorized_computer true the command has no code, turnzero authorize --mint <id>, whether or not it is passed. A mint whose grants are ["tzmesh"] alone may pass it too, for turnzero tzmesh register --mint <id>. Pass it only where the command's first act printed it; another value, or the argument on any other mint, is refused.
Access and action metadata #
{
"name": "mint_token",
"resource": "token",
"tier": "reversible",
"surface": "account",
"addresses": [
"tzcloud"
],
"summary": "Mint a token from the connected session: its scope (the account, or one application), an optional expiry and label, and the grants requested, each given only where the session holds it. The space grant `issues`, given by any session of the account, takes one space the account holds in `space` and the `level` it reaches it at, `report`, `contribute`, or `owner`. Its `label` is required and identifies the holder. Every call passes `code_challenge`, the S256 challenge of the verifier the turnzero command keeps, which the command prints and `login` carries to its page. The call returns a one-time token code's line and no value, or, with `authorized_computer` true, the held line `turnzero authorize --mint <id>`, which holds no code. A mint whose grants are `[\"tzmesh\"]` alone may pass `completion` too, its held line `turnzero tzmesh register --mint <id>`. The command's exchange under that code, on the HTTP action route with `code_verifier`, or under the verifier with `mint` for the held line, returns the value once, and a call that passes no challenge is refused `invalid_request`. A token carrying `issues` is minted only for an account holding tzTrack, and otherwise refused `blueprint_required` with nothing minted. A token carrying `tzmesh`, given by any session of an account holding that product profile with a `label` and no `level`, is refused `tzmesh_required` where the account lacks it. A token carrying `tztrack`, given by any session of an account holding that product profile with a `label` and no `level`, is refused `blueprint_required` where the account lacks it; a `tzmesh` or `tztrack` token lives at most 180 days, 180 where `expires_in_days` is absent, and its value is the signed form its product's service verifies. A token carrying `test_end_users`, given by any session of the account on an account or an application token, takes a `label` for the holder, unique among the unrevoked tokens carrying it in its scope, lives at most 180 days, 180 where `expires_in_days` is absent, and is refused beside a narrow grant and on an authorized computer's mint; it admits test end users wherever the account's session is admitted.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"openWorldHint": false
}
}
MCP catalog entry #
{
"name": "mint_token",
"title": "Create access token",
"tier": "reversible",
"summary": "Mint an API token for `turnzero` or a CI job.\n\nA person's signed-in connection is required. A connection presenting an account-wide minted token is refused `session_credential_required`.\n\nThe first command runs on the target computer: `turnzero authorize`, `turnzero token request` or `turnzero tzmesh register`. It prints `code_challenge`. `completion` is passed only where that command prints it. `awaiting_command` returns a completing line, without a token value.\n\nThat line runs once, unchanged, on the same computer before `expires_at`. A `token claim` line carries a one-time credential. Only the owner runs it, outside AI tools. Authorization and tzMesh registration run in the signed-in AI tool's shell. After authorization, you tell the owner the token's label, expiry and that `revoke_token` ends it. Token values stay out of the conversation.",
"owners": [
"API-L0-05",
"API-L0-17",
"MAPI-14",
"MAPI-12"
],
"scenario": "API-L0-05"
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["scope_kind","code_challenge"] |
| / |
Account-wide or bounded to one application. Allowed values: ["account","application"] |
| / |
Required only for application scope: the application id the token is bounded to. Refused with account scope. Type: string |
| / |
Extra grants. destructive and super_admin require the session to hold them, the latter granted by an operator. issues, tzmesh, tztrack and test_end_users need only the session. Application scope permits only destructive and test_end_users, else grant_scope_refused.Type: array |
| / |
Allowed values: ["destructive","super_admin","synthetic_seed_purge","synthetic_estate","publication","feedback_queue","issues","tzmesh","tztrack","test_end_users"] |
| / |
With issues, an account-held issue space from list_issue_spaces.Type: string Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ |
| / |
issues: report: file, follow, check, read, watch, unwatch; contribute adds update, comment, relate, next, give back, wait, cache archive, task close/reopen. owner admits all; read_space, other close/reopen need it. tzmesh/tztrack: no levels; minted admin bounds no product call.Allowed values: ["report","contribute","owner","read","chat","admin"] |
| / |
With tzmesh, tztrack or test_end_users, 1–180 days, default 180. Without those grants or authorized_computer, omission means no expiry.Type: integer Minimum: 1 Maximum: 3650 |
| / |
Shown by list_tokens. Required and printable for issues, test_end_users, tzmesh or tztrack. Unique among unrevoked issues labels in the space, or test_end_users labels in scope. tzmesh and tztrack labels may repeat.Type: string Maximum length: 120 Minimum length: 1 |
| / |
From the first command on the target computer. --origin must match the connection, or --tzmesh-estate for tzMesh, defaulting from --origin. Same options reuse a pending challenge. After expiry, the first command runs again.Type: string Pattern: ^[A-Za-z0-9_-]{43}$ |
| / |
True authorizes that computer: account scope, at most 30 days, default 30. The signed-in tool then tells the owner the token's label, expiry and that revoke_token ends it.Type: boolean |
| / |
The exchange's one member, sent by the turnzero command on the HTTP action route under the token code its line carries: the verifier whose S256 challenge the mint carried. No tool carries it. Type: string HTTP action route only, never an MCP tool argument: true |
| / |
Only when printed by authorize or, for grants ["tzmesh"] alone, tzmesh register. Other mints refuse it. With authorized_computer, the line is turnzero authorize --mint <id>, without a code, whether or not completion is supplied.Type: string Allowed values: ["mint"] |
| / |
The held exchange's one member, sent by the turnzero command on the HTTP action route under the verifier it keeps. It is the mint's id from its --mint line, or device, the poll turnzero login --device makes for the row the computer login page's device mode wrote. No tool carries it.Type: string Pattern: ^(?:device|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ HTTP action route only, never an MCP tool argument: true |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","token"] Additional properties: false |
| / |
Required value: 1 |
| / |
Type: object Required fields: ["scope_kind","application","grants","label","expires_at"] Additional properties: false |
| / |
Type: string |
| / |
Allowed values: ["account","application"] |
| / |
Type: ["string","null"] |
| / |
Type: array |
| / |
Allowed values: ["destructive","super_admin","synthetic_seed_purge","synthetic_estate","publication","feedback_queue","issues","tzmesh","tztrack","test_end_users"] |
| / |
Type: ["string","null"] |
| / |
Whether the token is an authorized computer's: on the mint's answer and on the exchange's answer. Type: boolean |
| / |
The space the issues grant applies to; present on a token that carries the grant alone. Type: string Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ |
| / |
The level the issues grant reaches its space at, report, contribute, or owner, or a tzmesh or tztrack token's level, read, chat, or admin, a mark that bounds no call of its product. It is present on a token that carries one of the three grants alone.Allowed values: ["report","contribute","owner","read","chat","admin"] |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: ["string","null"] |
| / |
Type: ["string","null"] |
| / |
On a product token alone, one holding the tzmesh or tztrack grant: a sentence saying the last-use time counts only requests made to this platform. The product's own service checks the token without asking this platform, so its uses there are not recorded and a null time does not mean the token is unused.Type: string |
| / |
The token's value, returned once, by the exchange the turnzero command makes under a token code and by no call under a session credential: a mint returns a line and no value. Type: string |
| / |
On the mint's answer: the token code is minted and its line has yet to run. Required value: awaiting_command |
| / |
In the mint's result: one line, for macOS and Linux. Where a call has authorized_computer true, it is turnzero authorize --mint <id>, which carries the mint's id and no code. Where a mint whose grants are ["tzmesh"] alone passed completion, it is turnzero tzmesh register --mint <id>, which carries no code either. Otherwise it pipes the one-time token code to turnzero token claim, echo <code> | turnzero token claim, ending with --origin <origin> when the responding origin is not the command's default. The account's owner runs it in a terminal outside the AI coding tool, and no tool runs it. When tzTeam's connect made the challenge, an AI tool runs no line the call returns and pipes the code to that command's own completing line. A line that carries a token code is a credential until expires_at; a held line is none.Type: string |
| / |
On the mint's answer: the same line for every Windows shell, with turnzero.cmd where its head says turnzero.Type: string |
| / |
With the state awaiting_command: 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 on their computer. 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_command: command_npx's line for every Windows shell, with npx.cmd where its head says npx.Type: string |
| / |
On the mint's answer: when the token code stops serving, as an ISO 8601 instant, the served token_code_seconds after the call and never past the minting session's expiry. A line run after it is refused token_code_refused.Type: string |
| / |
On the mint's answer, for a line that carries a token code: that the line is a credential until expires_at, to run once as given and paste into nothing but the terminal that runs it, and who runs it. For the held line: that it gives the mint's id and holds no credential, and to run it once on the computer that printed the challenge.Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"scope_kind",
"code_challenge"
],
"properties": {
"scope_kind": {
"enum": [
"account",
"application"
],
"description": "Account-wide or bounded to one application."
},
"application": {
"type": "string",
"description": "Required only for application scope: the application id the token is bounded to. Refused with account scope."
},
"grants": {
"type": "array",
"items": {
"enum": [
"destructive",
"super_admin",
"synthetic_seed_purge",
"synthetic_estate",
"publication",
"feedback_queue",
"issues",
"tzmesh",
"tztrack",
"test_end_users"
]
},
"description": "Extra grants. `destructive` and `super_admin` require the session to hold them, the latter granted by an operator. `issues`, `tzmesh`, `tztrack` and `test_end_users` need only the session. Application scope permits only `destructive` and `test_end_users`, else `grant_scope_refused`."
},
"space": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "With `issues`, an account-held issue space from `list_issue_spaces`."
},
"level": {
"enum": [
"report",
"contribute",
"owner",
"read",
"chat",
"admin"
],
"description": "`issues`: `report`: file, follow, check, read, watch, unwatch; `contribute` adds update, comment, relate, next, give back, wait, `cache` archive, task close/reopen. `owner` admits all; `read_space`, other close/reopen need it. `tzmesh`/`tztrack`: no levels; minted `admin` bounds no product call."
},
"expires_in_days": {
"type": "integer",
"minimum": 1,
"maximum": 3650,
"description": "With `tzmesh`, `tztrack` or `test_end_users`, 1–180 days, default 180. Without those grants or `authorized_computer`, omission means no expiry."
},
"label": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Shown by `list_tokens`. Required and printable for `issues`, `test_end_users`, `tzmesh` or `tztrack`. Unique among unrevoked `issues` labels in the space, or `test_end_users` labels in scope. `tzmesh` and `tztrack` labels may repeat."
},
"code_challenge": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "From the first command on the target computer. `--origin` must match the connection, or `--tzmesh-estate` for tzMesh, defaulting from `--origin`. Same options reuse a pending challenge. After expiry, the first command runs again."
},
"authorized_computer": {
"type": "boolean",
"description": "True authorizes that computer: account scope, at most 30 days, default 30. The signed-in tool then tells the owner the token's label, expiry and that `revoke_token` ends it."
},
"code_verifier": {
"type": "string",
"x-wire-only": true,
"description": "The exchange's one member, sent by the turnzero command on the HTTP action route under the token code its line carries: the verifier whose S256 challenge the mint carried. No tool carries it."
},
"completion": {
"type": "string",
"enum": [
"mint"
],
"description": "Only when printed by `authorize` or, for grants `[\"tzmesh\"]` alone, `tzmesh register`. Other mints refuse it. With `authorized_computer`, the line is `turnzero authorize --mint <id>`, without a code, whether or not `completion` is supplied."
},
"mint": {
"type": "string",
"pattern": "^(?:device|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$",
"x-wire-only": true,
"description": "The held exchange's one member, sent by the turnzero command on the HTTP action route under the verifier it keeps. It is the mint's id from its `--mint` line, or `device`, the poll `turnzero login --device` makes for the row the computer login page's device mode wrote. No tool carries it."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"token"
],
"properties": {
"contract_version": {
"const": 1
},
"token": {
"type": "object",
"required": [
"scope_kind",
"application",
"grants",
"label",
"expires_at"
],
"properties": {
"id": {
"type": "string"
},
"scope_kind": {
"enum": [
"account",
"application"
]
},
"application": {
"type": [
"string",
"null"
]
},
"grants": {
"type": "array",
"items": {
"enum": [
"destructive",
"super_admin",
"synthetic_seed_purge",
"synthetic_estate",
"publication",
"feedback_queue",
"issues",
"tzmesh",
"tztrack",
"test_end_users"
]
}
},
"label": {
"type": [
"string",
"null"
]
},
"authorized_computer": {
"type": "boolean",
"description": "Whether the token is an authorized computer's: on the mint's answer and on the exchange's answer."
},
"space": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "The space the issues grant applies to; present on a token that carries the grant alone."
},
"level": {
"enum": [
"report",
"contribute",
"owner",
"read",
"chat",
"admin"
],
"description": "The level the issues grant reaches its space at, report, contribute, or owner, or a `tzmesh` or `tztrack` token's level, read, chat, or admin, a mark that bounds no call of its product. It is present on a token that carries one of the three grants alone."
},
"created_at": {
"type": "string"
},
"expires_at": {
"type": [
"string",
"null"
]
},
"revoked_at": {
"type": [
"string",
"null"
]
},
"last_used_at": {
"type": [
"string",
"null"
]
},
"last_used_note": {
"type": "string",
"description": "On a product token alone, one holding the `tzmesh` or `tztrack` grant: a sentence saying the last-use time counts only requests made to this platform. The product's own service checks the token without asking this platform, so its uses there are not recorded and a null time does not mean the token is unused."
}
},
"additionalProperties": false
},
"value": {
"type": "string",
"description": "The token's value, returned once, by the exchange the turnzero command makes under a token code and by no call under a session credential: a mint returns a line and no value."
},
"state": {
"const": "awaiting_command",
"description": "On the mint's answer: the token code is minted and its line has yet to run."
},
"command": {
"type": "string",
"description": "In the mint's result: one line, for macOS and Linux. Where a call has `authorized_computer` true, it is `turnzero authorize --mint <id>`, which carries the mint's id and no code. Where a mint whose grants are `[\"tzmesh\"]` alone passed `completion`, it is `turnzero tzmesh register --mint <id>`, which carries no code either. Otherwise it pipes the one-time token code to `turnzero token claim`, `echo <code> | turnzero token claim`, ending with `--origin <origin>` when the responding origin is not the command's default. The account's owner runs it in a terminal outside the AI coding tool, and no tool runs it. When tzTeam's `connect` made the challenge, an AI tool runs no line the call returns and pipes the code to that command's own completing line. A line that carries a token code is a credential until `expires_at`; a held line is none."
},
"command_windows": {
"type": "string",
"description": "On the mint's answer: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`."
},
"command_npx": {
"type": "string",
"description": "With the state `awaiting_command`: 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 on their computer. 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_command`: `command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx` (PLD-L0-94)."
},
"expires_at": {
"type": "string",
"description": "On the mint's answer: when the token code stops serving, as an ISO 8601 instant, the served `token_code_seconds` after the call and never past the minting session's expiry. A line run after it is refused `token_code_refused`."
},
"detail": {
"type": "string",
"description": "On the mint's answer, for a line that carries a token code: that the line is a credential until `expires_at`, to run once as given and paste into nothing but the terminal that runs it, and who runs it. For the held line: that it gives the mint's id and holds no credential, and to run it once on the computer that printed the challenge."
}
},
"additionalProperties": false
}
}
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