---
title: Mint a token
description: Mint a limited, revocable token from your signed-in session for a script, a pipeline, or a contractor's tool, and list and revoke them.
slug: /guides/mint-a-token
order: 34
visibility: public
redirects_from: []
---

# Mint a token

Prompt:

> I need a token so GitHub Actions can deploy this app.

Also works:

- "Give the contractor a way to read this app's logs without my sign-in."
- "The token in the pipeline leaked. Kill it and make a new one."
- "Which tokens are still live on this account?"

Your AI tool mints a token in three moves, so its value never passes through the chat. `turnzero token request` prints a challenge, `mint_token` takes it, and you run the `token claim` line that call returns, in a terminal of your own ([step 1](#1-mint-it)). A job then sends the token as a bearer credential, read from `TURNZERO_CLOUD_MINTED_TOKEN` ([step 3](#3-use-it)).

## What your AI tool does

- Calls `tzcloud_list_applications` for the application's identifier, and `list_tokens` so it mints no duplicate and finds the token to revoke.
- Runs `token request`, calls `mint_token` with the challenge it printed, and gives you the `token claim` line the call returns, as [step 1](#1-mint-it) shows. It never runs that line, so the value appears in no chat or file it commits.
- For an unattended `provision`, a CI job or a script of your own, mints a token bounded to the application, as [Running on your machine](/cloud/concepts/turnzero-command/#running-on-your-machine) describes. A [local run](/cloud/concepts/glossary/#local-run) from your AI tool needs no token, because its line claims a [secret grant](/cloud/concepts/glossary/#secret-grant) with the verifier the command keeps on your computer.
- Requests no grant unless the task needs a destructive action, sets `expires_in_days` when the task has an end, and sets a `label` that names the consumer.
- For a deploy job, writes the workflow step that runs the deploy line under the stored token.
- On a leak, calls `revoke_token` with the token's `id` from `list_tokens`, then mints a replacement the same way.
- Asks you only to run the `token claim` line in a terminal of your own. `mint_token` and `revoke_token` are [reversible-tier](/cloud/concepts/glossary/#management-action-tier) actions, so neither needs your approval; a destructive action the token requests later is approved by a person in the browser.

## What you need

- A safe place to keep the token once it's created, such as your pipeline's secret store or your AI tool's credential settings. Never save it in a file you commit to your project.
- For a token with the `issues` grant, an account with tzTrack access; check its products with `read_account`.

## Before your AI starts

**For the AI tool:** Check the following before starting.

- A signed-in session in your connected tool ([Connect your AI assistant](/cloud/getting-started/connect-your-tool/)). A minted token or an application's [platform credential](/cloud/concepts/glossary/#platform-credential) cannot mint.
- For an application-scoped token, the application's identifier from `tzcloud_list_applications`.

## Steps

### 1. Mint it

A token is minted in three moves, so its value never passes through your AI coding tool. This example mints a token for a GitHub Actions job that deploys one application.

First, run `token request` on the computer where you will run `token claim`. For a remote runner, use your own computer and pipe the claim's output into the runner's secret store, as the GitHub example below shows. `token request` keeps a verifier there and prints a challenge, which is public. On Windows, the line starts with `turnzero.cmd` in place of `turnzero`.

```text
turnzero token request
```

Then your AI tool calls `mint_token` from your signed-in session, with the printed challenge as `code_challenge`. The challenge below is an invented example: always pass the one `token request` printed.

```json
{
  "code_challenge": "C2HDeKDoksEgtGXIE0Vk9MYtS8Ataf9qEJ-KNLiFT_M",
  "scope_kind": "application",
  "application": "<application id>",
  "expires_in_days": 90,
  "label": "github-actions-deploy"
}
```

The call returns a `turnzero token claim` command, never the token's value. Run it yourself in a terminal outside the AI coding tool, on the same computer, piping its output into your secret store or a protected file. Check that it runs `turnzero token claim` and sends the output only to your secret store or the file you chose. This example shows the returned command with its code replaced by `<code>`, piped into GitHub's secret store:

```text
echo <code> | turnzero token claim | gh secret set TURNZERO_CLOUD_MINTED_TOKEN
```

The token now lives in the repository's secrets, and the value never appeared on your screen.

To save the token in a file from Windows PowerShell, pipe the returned Windows command into `Set-Content`. Replace `<private token file>` with a path outside your project:

```powershell
echo <code> | turnzero.cmd token claim | Set-Content -LiteralPath '<private token file>' -Encoding ascii -NoNewline
```

Windows PowerShell 5.1's `>` writes UTF-16 text, which [`turnzero secret store --value-file`](/cloud/guides/supply-a-secret-value-without-exposing-it/) rejects; this form saves the token as plain text without adding a line ending.

The members `mint_token` takes:

| Member | What it contains |
| --- | --- |
| `code_challenge` | Required. The challenge `token request` printed, 43 characters. |
| `scope_kind` | Required. `account` or `application`. The scope is fixed at minting. |
| `application` | The application's identifier. Required for application scope, and refused for account scope. |
| `grants` | Optional. An array of `destructive`, `super_admin`, `synthetic_seed_purge`, `synthetic_estate`, `publication`, `feedback_queue`, `issues`, `tzmesh`, `tztrack`, and `test_end_users`. The product grants `tzmesh` and `tztrack` require access to that product. A product token lasts 180 days by default and no more than 180 days. Its value is signed for the product's own service. Request only what the unattended task needs. |
| `space` and `level` | Only with the `issues` grant: see [A token for one issue space](#a-token-for-one-issue-space). |
| `expires_in_days` | Optional. An integer from 1 to 3650. Without it, the token does not expire. A product's token and a token with the `test_end_users` grant are the exceptions: each lives 180 days without it, and takes at most 180. |
| `label` | Optional. 1 to 120 characters, to identify the token later. Required with the `issues` grant, the `test_end_users` grant, or a product's grant. |
| `authorized_computer` | Optional. `true` for an [authorized computer](/cloud/concepts/glossary/#authorized-computer)'s own token, which `authorize`'s call names when your signed-in tool authorizes the computer. |

A token gets only the grants you ask for, and only ones your session has. With the `destructive` grant, a token can only request a destructive action, and a person approves it in the browser. The `super_admin`, `synthetic_seed_purge`, `synthetic_estate`, `publication`, and `feedback_queue` grants are for platform staff ([Minted tokens](/cloud/concepts/sign-in-sessions-and-tokens/#minted-tokens)), and any other session's mint refuses them `grant_not_held`. An application-scoped token cannot have any of those, the `issues` grant, or a product's grant. A token cannot mint another token. A token bounded by `synthetic_seed_purge` can only seed a synthetic test account, purge it, read that purge, and make public reads.

An application-scoped token works on its one application. It can call:

- actions whose subject is that application;
- `read_account` and `tzcloud_read_plan_quotas`;
- `read_context` and `read_documentation`;
- the read of a [pending action](/cloud/concepts/glossary/#pending-action) whose subject is that application;
- `tzcloud_store_secret`, with `replace: true` for a replacement, when it names that application.

Every other action refuses it 403 `token_scope_refused`, `tzcloud_list_secrets` among them, because it lists the whole account. Calling `tzcloud_halt_environment` on production to stop it is refused 403 `account_credential_required`. Resuming it with `tzcloud_halt_environment` and `resume: true` is allowed.

#### A token for a CI job

A continuous integration (CI) job runs with no person present, and its token stays in the job's settings for as long as the job exists. So mint that token with two limits, as the example above does:

- `scope_kind` `application`, with the one application the job deploys. A copy of the token can then act on that application and on no other.
- `expires_in_days`, set to how long the job needs the token. A copy that leaks stops working at the expiry, even if no one notices the leak and revokes it. Mint a replacement before the expiry, and store it the same way.

Run the `token claim` line `mint_token` returns in a terminal of your own, piped into the job's secret store. Have the job set the stored value as the environment variable `TURNZERO_CLOUD_MINTED_TOKEN`. The turnzero command reads the token from that variable, never from an argument. This workflow installs the command and deploys the application on every push to `main`. Where the application is not at the repository's root, add `working-directory:` naming its folder to the last step.

```yaml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install -g turnzero
      - run: turnzero deploy --application <application id>
        env:
          TURNZERO_CLOUD_MINTED_TOKEN: ${{ secrets.TURNZERO_CLOUD_MINTED_TOKEN }}
```

[A minted token in the environment](/cloud/concepts/how-the-turnzero-command-finds-its-credential/#a-minted-token-in-the-environment) says how the command sends the token and how the line ends.

#### The challenge and the line

The challenge comes from `token request` for a token this guide describes, or from `authorize` for the computer's own token, when your signed-in tool authorizes the computer. A `mint_token` call without one is refused 400 `invalid_request`.

The call returns `state: awaiting_command`, `expires_at`, `token`, and `detail`. It gives the line in four forms: `command` and `command_windows` for an installed turnzero, and `command_npx` and `command_npx_windows` through npx.

For the authorized-computer line, your AI tool first runs `command_npx`, or `command_npx_windows` on Windows, with or without a global installation. [Running and writing lines](/cloud/concepts/turnzero-command/#running-and-writing-lines) explains what to do if npx can't run here. The `token claim` line is still for you to run in your own terminal; your AI tool must never run it.

The `token claim` line is a credential until `expires_at`, five minutes by default. An authorized computer's `authorize --mint <id>` line, in its npx and installed forms, holds no code and is no credential. Run it once, as given, and paste it into nothing but the terminal that runs it. Read the line's origin and application before you run it.

| Line | Who runs it | Where the value goes |
| --- | --- | --- |
| `authorize --mint <id>`, in its npx or installed form | Your signed-in AI coding tool, for an [authorized computer](/cloud/concepts/glossary/#authorized-computer)'s token, which it then tells you about. The line holds no code and is no credential. Your own `turnzero login` needs no line. | Into this computer's credential file. |
| `echo <code> \| turnzero token claim` | You, in a terminal outside the AI coding tool, on the computer that printed the challenge. A tool never runs it. | Printed once to that terminal, or into the command piped after it. |

`token claim` refuses before exchanging the code if its standard error is not a terminal. Your AI tool must not run it, even if it can open a terminal. An AI coding tool's integrated terminal is still the tool's, so use a terminal of your own. Where your AI tool's shell runs on another computer, run `token request` and `token claim` on your own computer and give the tool the challenge.

For a token file in Windows PowerShell, use the `Set-Content -Encoding ascii -NoNewline` form in [step 1](#1-mint-it) to keep the token's bytes unchanged.

If the value appears in a chat, a log, or a commit, revoke it and mint a replacement.

#### A token for one issue space

The `issues` grant lets a program work in one [issue space](/cloud/concepts/glossary/#issue-tracking-space) of your account without the space's own credential, which the platform keeps. Give the space's identifier from `list_issue_spaces` in `space`, the [grant level](/cloud/concepts/glossary/#grant-level) in `level` (`report`, `contribute`, or `owner`, which [Keep your own issue list](/cloud/guides/keep-your-own-issue-list/#2-mint-the-space-s-token) describes), and a `label` naming who uses the token.

The grant and `relay_issue_act` require tzTrack access, which every account holds and `read_account` lists among your account's products. If the mint or a call to `relay_issue_act` returns 403 `blueprint_required`, repeat the request. Report a persistent refusal with `submit_feedback`.

For a space shared with yours ([Share the space](/cloud/guides/keep-your-own-issue-list/#share-the-space)), `level` cannot exceed your member level. A higher one refuses `issues_level_refused`. Member names are Viewer (`view`), Reporter (`report`), Contributor (`contribute`) and Admin (`owner`). Owner means the owning account, which alone manages membership. Minted grants remain `report`, `contribute` or `owner`; the names do not change those values.

Your member row's `restricted` and any `accounts` bound still limit the token's calls. A bounded row reads only its group's reports and no restricted issue, and admits only its allowed reads, filing and work on group-opened tasks. The service refuses an off-list call as `grant_required`; the relay returns that reason under `issue_refused`. Removing the member ends access on the next call. [Sharing a space](https://turnzero.ai/tztrack/concepts/sharing-a-space/) gives visibility and the bounded list.

The label uses printable characters, and no other unrevoked token for the space may have it. Writes are recorded under that label. The token calls `relay_issue_act` for one space, `list_tokens`, and the [public reads](/cloud/concepts/glossary/#public-reads); other actions refuse `issues_bounded`. [Keep your own issue list](/cloud/guides/keep-your-own-issue-list/) explains the levels.

#### A token for test end users

The `test_end_users` grant lets a pipeline or an agent with no person present create, read, and sign in [test end users](/cloud/guides/test-sign-in-with-test-end-users/) on production, and on a workforce application's two environments. A token without the grant is refused there with `test_end_users_not_admitted`. Your account's own session needs no grant.

The grant keeps the token's other permissions. It can be on an account-scoped token or on a token for one application, which can then act only on that application's test end users. It can go with `destructive`, and with `super_admin` on an account-scoped token. It cannot go with a grant that bounds its token to one issue space or one product, such as `issues` or `tztrack`, and an [authorized computer](/cloud/concepts/glossary/#authorized-computer)'s token cannot have it. Each of those is refused 400 `invalid_request`.

Give a `label` that names the holder, in printable characters. No other unrevoked token with the grant in the same scope may have that label. The control plane's log records it at each creation the token makes on production, or on a workforce realm. The token lives at most 180 days, and 180 when `expires_in_days` is omitted.

### 2. List and revoke

`list_tokens` returns each token's identifier, scope, grants, and label, without the value, and `space` and `level` on a token with the `issues` grant. It also returns when the token was minted, when it expires, and when it was last used.

The last-use time counts only requests this platform serves. A product token's own service checks the token without asking this platform, so its uses there are not counted. Its row carries `last_used_note` saying so, and a null time there does not mean the token is unused ([Product tokens](/cloud/concepts/sign-in-sessions-and-tokens/#product-tokens)). On any other token, a null last-use time means no request has used it yet.

`revoke_token` revokes a token by its identifier. Requests using it are then refused at once on the HTTP API and the MCP endpoint. On the storage, logging, and egress routes, the refusal starts within the credential interval that [Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/#when-an-ending-takes-effect) gives. A product's own service refuses a revoked product token within about a minute, when it next reads the platform's revocation list. Revoking the same token again keeps the first revocation's time.

`list_tokens` lists a revoked or expired token for thirty days after it ended. The platform then deletes its row, and `revoke_token` naming it returns `not_found`.

### 3. Use it

Send the token as a bearer credential to the HTTP address on the action's [reference page](/cloud/reference/action-catalog/). Every action accepts `POST`, and observe actions also accept `GET`. The MCP server accepts the token too, with its scope and grants.

A script with no MCP client can call `create_application` or `submit_manifest` in the same way, within its token's scope and grants. `create_application` needs an account-scoped token because the application does not yet exist. If you have no token, use a signed-in connected AI tool once to [mint one](#1-mint-it). Claim it in your own terminal into a secret store; the script reads it through `TURNZERO_CLOUD_MINTED_TOKEN`.

This script prints an application's status under the token. It reads the token from `TURNZERO_CLOUD_MINTED_TOKEN`, which your job sets from its secret store, or your shell for one line as [Setting the variable for one line](/cloud/concepts/turnzero-command/#setting-the-variable-for-one-line) shows. Run it as `node status.mjs <application id>`.

```js
// status.mjs: prints the status of the application named on the command line, under a minted token.
const response = await fetch('https://tzcloud.turnzero.ai/v1/read_status', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.TURNZERO_CLOUD_MINTED_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ application: process.argv[2], brief: true }),
});
const answer = await response.json();
if (!response.ok) throw new Error(`${answer.error}: ${answer.detail}`);
console.log(answer.summary);
```

A call that sends a member the action does not take is refused 400 `invalid_request`. The refusal gives the members the action takes or, for a long list, their count and the action's reference page. Every action a token performs is recorded under that token's own identity, so you can tell which consumer did what.

An application-scoped token also works on the storage, egress, and logging routes within its scope. An account-scoped token works on the storage routes and keyed upstreams. The logging routes and the platform's `ai-allowance` upstream need an application-scoped token.

A token belongs to no environment. So a call under it names the environment in the header `x-turnzero-cloud-environment`, `development` or `production`, on these routes, and is refused 400 `environment_required` without it:

- the storage file routes, the file list, and the transfer-grant mint ([Store files](/cloud/guides/store-files/));
- the keyed egress route;
- the session [verification route](/cloud/concepts/glossary/#verification-route), where the body member `environment` can be sent instead.

A write to the storage routes also gives the acting identity in the header `X-Acting-Identity`, as [An upload under a minted token](/cloud/guides/store-files/#an-upload-under-a-minted-token) shows for a deploy artifact. The logging ingest reads the environment from each batch's own `environment` member instead; a header sent beside it must match, or the batch is refused 403 `environment_mismatch`.

## Expected result

`mint_token` returns `state` `awaiting_command`, the line, its `expires_at`, and `token`, the properties the line mints with, but no value and no `id`. The line's run mints the token and gives its value once, where the line's form says. `list_tokens` then lists the token with its `id` and no value, its `last_used_at` null until a request to this platform uses it. `revoke_token` returns the `id` and `revoked_at`, and a later request under the token is refused.

## Refusals

See the [refusals reference](/cloud/reference/refusals/) for other platform errors.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `session_credential_required` | 403 | `mint_token` was called under an account-scoped minted token. An application-scoped token is refused `token_scope_refused` first, and a platform credential `app_credential_not_admitted`. | Call it from the signed-in session in your connected tool. An unattended `provision` runs under a token bounded to the application, minted with `mint_token` from your signed-in session. For other calls, the token you already have may work. [Step 3](#3-use-it) says which routes take which token. |
| `invalid_request` | 400 | A member breaks the rules in step 1, `code_challenge` among them, or `revoke_token` has no `id`; `detail` names it. With the `issues` grant, this includes a missing `space`, `level`, or `label`, a label with a character that is not printable, and a label another unrevoked token for the same space already has. A `space` or `level` sent without the `issues` grant is refused here too, unless `space` names a space your account does not own. | Correct the named member and call again. |
| `space_not_owned` | 403 | `space` names no space your account owns or can access through membership, or does not match the token’s space. | Use an accessible identifier from `list_issue_spaces`, or create a space with `tztrack_create_space`. |
| `blueprint_required` | 403 | The platform reports that the account does not hold tzTrack, although every account holds it. HTTP calls to `"create_space"`, `"share_space"`, `"list_space_members"`, `"rename_space"`, or `"relay_issue_act"` are refused the same way. | Every account has tzTrack, so there is nothing to add. Repeat the request; `read_account` lists the products the account holds. |
| `issues_level_refused` | 403 | With the `issues` grant, `level` is above the level the shared space's owner gave your account. | Mint at that level or below, or ask the owner for a higher one. |
| `no_such_application` | 404 | `application` names no application of your account. | Use the identifier `tzcloud_list_applications` returns. |
| `application_other_account` | 403 | `application` names an application that another account holds, not the account the call is signed in as. The `detail` names the account the call acted as and nothing of the other one. | Compare `turnzero whoami` with `read_account` over your AI tool's connection. Make the call from the one signed in to the account that holds the application. |
| `grant_not_held` | 403 | The minting session does not have the requested grant; the refusal's `grant` member names it. | Leave the grant out, or mint from a session that has it. |
| `authorization_pending` | 400 | The device sign-in has not been approved; nothing was minted. | `login --device` keeps checking every five seconds until its request ends. Open the link for the sign-in you asked for and approve the named computer ([Sign in without a terminal](/cloud/concepts/how-the-turnzero-command-finds-its-credential/#sign-in-from-an-ai-tool-without-a-terminal)). |
| `token_code_refused` | 403 | The line's token code is unknown, expired, or already presented, its verifier did not match, its account is suspended, or the session that minted it has ended. Nothing was minted. | Call `mint_token` again with the challenge `token request` printed, and run the line it returns once. |
| `not_found` | 404 | `revoke_token` named an `id` that is not a token of your account, or a token whose row the platform deleted thirty days after it was revoked or expired. | Use an `id` from `list_tokens`. A deleted token is already refused everywhere, so nothing is left to revoke. |
| `synthetic_seed_purge_bounded` | 403 | A token with the `synthetic_seed_purge` grant, a platform staff grant, called an action outside the three it can call and the public reads; `admitted` lists the three. | Call the action from your signed-in session, or under a token minted without the grant. |
| `token_scope_refused` | 403 | An application-scoped token named another application, or called an action outside the list in step 1. | Use a token for that application, or an account-scoped token. |
| `environment_required` | 400 | A call under the token on a route listed in step 3 named no environment. | Send the header `x-turnzero-cloud-environment` with `development` or `production`, or the body member `environment` on the verification route. |

## Related

- [Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/) compares every credential and says what ends each one.
- [The turnzero command](/cloud/concepts/turnzero-command/#deploying-unattended) runs the deploy line under a minted token, and [Deploying from an area of your own](/cloud/guides/store-files/#6-the-deploy-area-and-deploying-from-an-area-of-your-own) shows a pipeline that uploads by itself.
- [What happens without asking](/cloud/concepts/what-happens-without-asking/) lists the actions a token requests and a person approves.
- [What happens without asking](/cloud/concepts/what-happens-without-asking/) explains the tiers behind a token's grants.
- [mint_token](/cloud/reference/actions/mint-token/), [list_tokens](/cloud/reference/actions/list-tokens/), and [revoke_token](/cloud/reference/actions/revoke-token/) in the generated reference give each action's arguments and result.
- [Glossary](/cloud/concepts/glossary/) defines the terms used on this page.
