Mint a token #
On this page
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). A job then sends the token as a bearer credential, read from TURNZERO_CLOUD_MINTED_TOKEN (step 3).
What your AI tool does #
- Calls
tzcloud_list_applicationsfor the application's identifier, andlist_tokensso it mints no duplicate and finds the token to revoke. - Runs
token request, callsmint_tokenwith the challenge it printed, and gives you thetoken claimline the call returns, as step 1 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 describes. A local run from your AI tool needs no token, because its line claims a secret grant with the verifier the command keeps on your computer. - Requests no grant unless the task needs a destructive action, sets
expires_in_dayswhen the task has an end, and sets alabelthat 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_tokenwith the token'sidfromlist_tokens, then mints a replacement the same way. - Asks you only to run the
token claimline in a terminal of your own.mint_tokenandrevoke_tokenare reversible-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
issuesgrant, an account with tzTrack access; check its products withread_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). A minted token or an application's 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.
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.
{
"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:
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:
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 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. |
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'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), 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_accountandtzcloud_read_plan_quotas;read_contextandread_documentation;- the read of a pending action whose subject is that application;
tzcloud_store_secret, withreplace: truefor 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_kindapplication, 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.
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 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 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'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 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 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 in level (report, contribute, or owner, which Keep your own issue list 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), 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 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; other actions refuse issues_bounded. 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 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'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). 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 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. 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. 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 shows. Run it as node status.mjs <application id>.
// 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);
- the keyed egress route;
- the session verification route, where the body member
environmentcan 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 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 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 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). |
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 compares every credential and says what ends each one.
- The turnzero command runs the deploy line under a minted token, and Deploying from an area of your own shows a pipeline that uploads by itself.
- What happens without asking lists the actions a token requests and a person approves.
- What happens without asking explains the tiers behind a token's grants.
- mint_token, list_tokens, and revoke_token in the generated reference give each action's arguments and result.
- Glossary defines the terms used on this page.