How do API tokens work — minting, expiry, revoking, and what does a 401 mean?

Short answerTokens are minted under the avatar menu → API tokens, shown once, valid for 90 days by default (the API accepts 1–365) and revoked from the same list, taking effect within a minute. A token has your account's permissions except managing users, and it can never mint another token. A 401 means the token is malformed, expired or revoked — mint a new one and log in again.

Minting a token

Open the avatar menu in the console and choose API tokens. Enter a name — the agent or machine that will hold it, such as claude-code or ci-runner — and click Mint one →.

The plaintext token, starting dw_pat_v1_, appears in an amber card once. Copy it, or copy the ready-made CLI login command, and click I've saved it. After that the console only knows the token's fingerprint; it cannot show the value again. Minting requires a signed-in browser session: a token cannot be used to mint tokens.

The console mints tokens that expire in 90 days. If you need a different lifetime, the API accepts days from 1 to 365 on POST /v1/tokens.

What a token can do

A token acts as you, with two limits that apply to everyone, including account owners:

It can never manage users or team members.
It can never mint another token.

Everything else follows your account: your runs, your credits, your permissions. Charges made through a token are recorded against it, so the token list and your usage breakdown show what each agent spent.

Reading the list

Each row shows the token's name and id, when it was last used (any call, to the hour) with the credits it has spent, and the expiry date. An expiry less than seven days away is highlighted so you can rotate before your agent starts failing.

Revoking and rotating

Click Revoke, then Confirm revoke?. Revocation takes effect within 60 seconds; a call made in that window may still succeed. To rotate, mint the new token first, update your agent, then revoke the old one.

npx @dawnwood/cli auth logout only deletes the copy on your machine. If a token may have leaked, revoke it in the console; deleting local copies is not enough.

When a call fails

Response	Meaning	What to do
`401`	The token is malformed, expired or revoked. Bearer authentication never falls back to another identity.	Mint a new token, run `auth login` again or update `DAWNWOOD_TOKEN`.
`403 a token cannot mint tokens`	You called the token API with a token.	Mint from a browser session.
`403` elsewhere	The action is reserved for Dawnwood staff, or the account is not active.	Use the console for that action, or contact support.
`402`	Not enough credits for a priced action.	Top up under Billing, then retry.
`400`	The request failed validation; the body names the field.	Fix the field. `create_run` most often fails on a short premise or a missing `compliance_ack`.

npx @dawnwood/cli whoami is the quickest health check: it returns your account if the stored token is valid and a 401 message if it is not.

Keeping tokens safe

Only the fingerprint is stored server-side; the CLI keeps the token in a file readable by your user only and never prints it.
Do not commit mcp.json or config.toml files that contain DAWNWOOD_TOKEN; prefer the stored CLI login, which keeps the token out of your project configuration.
In CI, put the token in the runner's secret store and expose it as DAWNWOOD_TOKEN.
Mint one token per agent or machine. When one leaks or a machine is retired, revoke just that token.

Still stuck? Email support@dawnwood.ai with your account email, the series, the episode and the segment or group — see what to include.