# Agent tokens

> What an agent token can and can't do, how read and act scopes follow the creator's role, expiry, revoking and rotating, and keeping one safe.

Last updated: October 16, 2026

Source: https://www.willo.ai/docs/ai-agents/agent-tokens

An agent token is how an AI agent proves it may work on your business. It belongs to one business and to the person who created it, and it carries a scope.

## Who can create one

Owners and admins of the business, on **Settings → AI Agents**, on the Builder plan and up. On a plan below that, the card shows an upgrade button instead. See [Pricing](https://www.willo.ai/pricing). A business can hold 20 live tokens at once. Create one per agent and per machine, so you can revoke one without breaking the others.

## Scopes

| Scope | What the agent can do |
| --- | --- |
| **Read-only** | Read the site's code, what the draft changes, the backend's schema, data and logs, edge functions, and the business itself: goals, roadmap, documents, content and analytics. |
| **Read + act** | Everything above, plus change the business: site files, backend tables, rows, functions and jobs, CMS content, documents, redirects, goals, roadmap and decisions. Anything risky stops for [approval](https://www.willo.ai/docs/ai-agents/approvals). |

A read-only token does not even see the act tools. Reads are free with either scope.

## The token follows its creator

A token can never do more than the person who created it can do right now. Willo checks that person's role on every call, not only when the token was made.

- Acting needs **editor** access or higher. If the creator drops to viewer, an act token keeps reading but its changes are refused with the code `rank`.
- Revenue figures and the Stripe customer list need **owner or admin**. If the creator stops being an owner or admin, those two reads are refused.
- If the creator leaves the business, the token stops working.

Tokens are also refused while the business is paused or suspended, and while its plan is below Builder or has lapsed. They are not revoked: they work again once the business is back on Builder or higher. They are revoked when the business is transferred to a new owner, and deleted with the business.

## Expiry

Pick 30, 90 or 365 days when you create the token. 90 is the default. The card warns when a token is within a week of expiring. An expired token is refused like a revoked one; create a new one and update the agent's environment variable.

## Shown once

Willo shows the token once, in the dialog after you create it, and stores only a hash of it. Nobody at Willo can read it back. After you close the dialog, the card lists the token by name and by its public id, the part after `willo_agt_` that is not secret, with when it was last used and how many calls it made this week.

## Revoking and rotating

**Revoke** on the token's row stops it at once: any agent still holding it is refused from the next call.

To rotate a token, create a new one, put it in the agent's environment variable, check the agent connects, then revoke the old one. Rotate straight away if a token was ever pasted into a chat, an issue, a commit or a shared document.

## Keeping it safe

- Keep the token in an environment variable, not in a config file. The setup steps on [Connect your agent](https://www.willo.ai/docs/ai-agents/connect-your-agent) do this for each client.
- Never commit a token. Every token has a fixed shape with a checksum, so a secret scanner can tell a real token from a look-alike. The exact pattern is on [Token format](https://www.willo.ai/docs/reference/tokens).
- Treat a token like a password to the business, scoped to what you chose.

## What a token can never do

Whatever its scope, a token cannot:

- approve an approval card, its own or anyone else's;
- see cards raised by other tokens or by Willo's chat;
- read the business's secrets, such as API keys added on the dashboard;
- reach any other business;
- invite people, change roles, change billing or delete the business;
- build or change Agent Programs. Those are built in Willo's chat.

Related: [Security model](https://www.willo.ai/docs/ai-agents/security-model), [Token format](https://www.willo.ai/docs/reference/tokens).