---
title: "mint_token"
description: "Generated reference for the management action mint_token: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/mint-token
order: 43
visibility: public
redirects_from: []
---

# mint\_token

Generated automatically from the [published contract sources](/cloud/reference/about/#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](/cloud/concepts/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

```json
{
  "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

```json
{
  "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<br>Required fields: \["scope\_kind","code\_challenge"\] |
| /<wbr>properties/<wbr>scope\_kind | Account\-wide or bounded to one application\.<br><br>Allowed values: \["account","application"\] |
| /<wbr>properties/<wbr>application | Required only for application scope: the application id the token is bounded to\. Refused with account scope\.<br><br>Type: string |
| /<wbr>properties/<wbr>grants | 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`\.<br><br>Type: array |
| /<wbr>properties/<wbr>grants/<wbr>items | Allowed values: \["destructive","super\_admin","synthetic\_seed\_purge","synthetic\_estate","publication","feedback\_queue","issues","tzmesh","tztrack","test\_end\_users"\] |
| /<wbr>properties/<wbr>space | With `issues`, an account\-held issue space from `list_issue_spaces`\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}$ |
| /<wbr>properties/<wbr>level | `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\.<br><br>Allowed values: \["report","contribute","owner","read","chat","admin"\] |
| /<wbr>properties/<wbr>expires\_in\_days | With `tzmesh`, `tztrack` or `test_end_users`, 1–180 days, default 180\. Without those grants or `authorized_computer`, omission means no expiry\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 3650 |
| /<wbr>properties/<wbr>label | 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\.<br><br>Type: string<br>Maximum length: 120<br>Minimum length: 1 |
| /<wbr>properties/<wbr>code\_challenge | 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\.<br><br>Type: string<br>Pattern: ^\[A\-Za\-z0\-9\_\-\]\{43\}$ |
| /<wbr>properties/<wbr>authorized\_computer | 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\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>code\_verifier | 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\.<br><br>Type: string<br>HTTP action route only, never an MCP tool argument: true |
| /<wbr>properties/<wbr>completion | 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\.<br><br>Type: string<br>Allowed values: \["mint"\] |
| /<wbr>properties/<wbr>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\.<br><br>Type: string<br>Pattern: ^\(?:device\|\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}\)$<br>HTTP action route only, never an MCP tool argument: true |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","token"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>token | Type: object<br>Required fields: \["scope\_kind","application","grants","label","expires\_at"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>scope\_kind | Allowed values: \["account","application"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>application | Type: \["string","null"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>grants | Type: array |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>grants/<wbr>items | Allowed values: \["destructive","super\_admin","synthetic\_seed\_purge","synthetic\_estate","publication","feedback\_queue","issues","tzmesh","tztrack","test\_end\_users"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>label | Type: \["string","null"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>authorized\_computer | Whether the token is an authorized computer's: on the mint's answer and on the exchange's answer\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>space | The space the issues grant applies to; present on a token that carries the grant alone\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}$ |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>level | 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\.<br><br>Allowed values: \["report","contribute","owner","read","chat","admin"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>created\_at | Type: string |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>expires\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>revoked\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>last\_used\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>last\_used\_note | 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\.<br><br>Type: string |
| /<wbr>properties/<wbr>value | 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\.<br><br>Type: string |
| /<wbr>properties/<wbr>state | On the mint's answer: the token code is minted and its line has yet to run\.<br><br>Required value: awaiting\_command |
| /<wbr>properties/<wbr>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\.<br><br>Type: string |
| /<wbr>properties/<wbr>command\_windows | On the mint's answer: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`\.<br><br>Type: string |
| /<wbr>properties/<wbr>command\_npx | 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\.<br><br>Type: string |
| /<wbr>properties/<wbr>command\_npx\_windows | With the state `awaiting_command`: `command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx`\.<br><br>Type: string |
| /<wbr>properties/<wbr>expires\_at | 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`\.<br><br>Type: string |
| /<wbr>properties/<wbr>detail | 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\.<br><br>Type: string |

## Complete payload contract

```json
{
  "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](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
