API Tokens
Mint a personal access token for the REST API, the MCP server or a pipeline, scope it to a team and optionally one project, tick its abilities, and revoke it.
By the end of this page you will know what a personal access token is, how to mint one that can do exactly what it needs and nothing more, where its plaintext is shown, and how to revoke it the moment it should stop working.
A personal access token is a credential that acts as you from outside the browser: a pipeline reporting a deployment, an AI coding agent reading a story's context over MCP, a script calling the REST API. Each token carries its own set of abilities and is scoped to one of your teams and, when you choose, to one project within it. It is a bearer secret: whoever holds the plaintext holds your access, within those limits.
Before you begin
| You need | Why |
|---|---|
| A team | A token acts within one team you own or belong to. You pick it when minting. |
| A project, if you are a guest | A guest's token must be confined to one of the projects they were invited to. |
| Somewhere safe to keep a secret | The plaintext is shown once. A password manager or your pipeline's secret store is where it should go. |
Where tokens live
Open Account Settings → API Tokens. The page lists your tokens, newest first:
| Column | What it shows |
|---|---|
| Name | The label you gave it, so you can tell the deploy pipeline from the agent. |
| Abilities | How many abilities it carries, the team and project scopes included. |
| Last used | When it last authenticated a request, or never. |
| Created | How long ago it was minted. |
| Row menu | Revoke. |
Tokens are personal: the page shows yours, and nobody else's appear on it.
Create a token
- Press Create Token.
- Type a Token name that says what will hold it, such as Deploy pipeline or Claude Code on the laptop.
- Pick the Team the token acts within. With one team the choice is made for you.
- Pick a Project to confine the token to one project, or leave Whole team to let it reach every project your role can see in that team. A guest has no whole-team option: the project is required.
- Tick the Abilities. The list is grouped by area, with a Toggle on each group and one for everything; the two project-reading abilities start ticked so a token is never minted inert. Tick only what the holder needs.
- Press Create token.
A flyout shows the plaintext once, with a copy button. Store it before you press Done; afterwards only a hash is kept and nothing can show the value again. If you lose it, revoke the token and mint another.
A token can do everything its abilities allow, as you, within its team and project. Treat the plaintext like a password: never paste it into a chat, a ticket or a repository, and revoke it the moment a device or a colleague that held it is gone.
What a token can and cannot do
- Abilities follow the same
entity:actiongrammar as role permissions. A token withwork-item:viewcan read work items and nothing else about them. - Your own permissions still apply. A token never does more than you could do yourself in that team; an ability you tick but do not hold answers with a refusal, not a backdoor.
- The team scope confines the token to one team. The project scope, when set, confines it further to one project; a guest's token always carries one.
- Minting more tokens is not something a token can delegate: a token minted through the API cannot carry
token:create, and can hand out only abilities it holds itself, so a leaked credential cannot grow.
Revoke a token
- Open the row menu and choose Revoke.
- Confirm. The row disappears and every client using that token starts failing on its next request.
Revocation cannot be undone and the secret cannot be recovered; mint a new token for a client that should keep working.
All the fields
What happens next
| Action | Event announced | Payload |
|---|---|---|
| Create a token | token.created | The abilities, the name, the token id, who owns it, and no expiry (tokens do not expire yet). |
| Revoke a token | token.revoked | The name, the token id and who owned it. |
Permissions
| Action | Who may do it |
|---|---|
| See and revoke tokens | You, for your own tokens |
| Mint a token | Anyone signed in, within their own teams |
| Confine to a project | Anyone who can see the project; a guest must |
Frequently asked
Related
- Webhooks: the other machine surface, pushing events to you.
- Roles: the permissions a token's abilities mirror.
- Browser sessions: the browser side of the same question.
How is this guide?
Last updated on
AI Settings
Read where the team's AI budget stands this month, set the cap and the warning line, read the statement per feature and model and the latest calls, and see which model each job runs on.
Webhooks
Register an endpoint that receives signed event payloads, pick its events, rotate its secret, pause or test it, and read and replay the delivery log.