Use an access token in a script or pipeline

Make a token for one workspace and the modules a script needs, give your organization's pipeline an identity of its own, and revoke either the moment you no longer trust it.

In short

An access token is a long secret a script or pipeline sends instead of signing in. You make one for one workspace and only the modules it needs, and revoke it the moment you no longer trust it. An organization can give its pipelines a service account that does not depend on any person.

Before you start

Who: anyone signed in with a confirmed email address can make personal tokens. Service accounts need "Manage access tokens and service accounts".
Plan: the modules the token reaches must be on your plan.
First: your password, and a place in your pipeline to keep the token. It is shown once.

Make your own token

Open Settings › "Sign-in & security" and find "Access tokens". Press "New token".
Type a name and choose the one workspace it works in: your personal workspace or an organization you belong to.
Under "What it may reach", choose "Read everything", "Read and write everything" or "Pick products", and set each product to "Read" or "Read and write". Choose only what the script needs.
Choose "Stops working after" - 90 days unless you choose otherwise, a year at most - type your password and press "Make token".
Copy the token now into your pipeline's secret store. It is shown once.

Use a token

Send it with every request as the header Authorization: Bearer followed by the token.
To check it before a pipeline starts, call the address ending in /api/v1/access/tokens/current. It answers the token's workspace, scopes and expiry.
To stop it, press "Revoke" beside it. It stops from its next request on.

Service accounts for an organization

A service account is a machine identity that belongs to the organization: no sign-in, inbox or seat, not a member, and it keeps working when whoever set it up leaves. The organization's Access › Tokens lists them for people who may manage access tokens - organization admins by default.

You can give an account only scopes you hold yourself, and make a token only for an account that reaches no more than you do.
Changing an account's scopes changes what its tokens reach at once; deleting it revokes them all.
What an account made or changed shows its own name in history, marked as a service account.
An account is in no team. Share the projects or boards it should work on with it by name, at Run or Edit - never Manage. At Run, a run against an environment marked Production waits for the project's managers to allow it.
Checks or schedules an account sets up for later do not run, so let the pipeline start its runs itself.
The same page lists the personal tokens members made for the organization. You can revoke one - its owner is told - but never see its secret. "Refuse personal access tokens" makes service accounts the only way in.

See what a token did

Find the token in your list, or in the organization's Access tokens if you manage them.
Press "Calls". Each request the token made shows newest first: the route it reached, the answer, how long it took and when.
Pick "Refused" or "Failed" to see only problems, or search for a route or a tool.
Press "Download" for a CSV of what you see. An organization's download is part of plans with the audit export.

Only the route, the record it named, the answer and the time are kept, for a year. Nothing that was sent or answered is kept, and neither is the address. An agent using the {{brand}} CLI shows the tool it used.

Limit an organization's tokens

Open the organization's Access tokens and go to "Token limits".
Choose "Longest a token may live". Tokens that would live longer end that many days from now when you save.
Under "Networks tokens work from", write one network per line, such as 203.0.113.0/24. Leave it empty to allow any address.
Press "Save limits".

The limits apply to every token of the organization: members' tokens, service accounts' tokens and coding agents. A token used from another network is refused, on top of the organization's own network rules.

Good to know

A token works as you and never does more than you may at that moment: a changed role, leaving the organization or a suspended account stops it at once.
It works in its workspace only. A token made for an organization reaches nothing of your personal workspace, and the other way round.
Scopes can be Analytics, API Tester, SQL Tester, Cache Tester, UI Tester, Boards, Planner, Notes, Designer and the Time tracker. The Time tracker scope is for your own time only, so a service account cannot have it.
A token never reaches members, roles, organization settings, billing, your account, the admin console, Chat, the assistant or Jobs. It cannot make tokens or links, change who can see something, decide as a person (verifications, triage, estimates, timesheets), delete for good or ask the AI.
With only Read, a token never gets a stored secret and never reaches your databases, caches or sites.
A reminder arrives a week and a day before a token expires. A token cannot be extended; make a new one. The list shows when and roughly where from each token was last used.
Tokens start with kamo_pat_ or kamo_svc_, so secret scanners can find one that leaked. Never put a token in a repository or an address.

If something goes wrong

401 "This access token is not valid" / "has expired" / "was revoked": make a new token.
403 "This access token has no scope for this module.": the answer names the scope that would allow it. Make a token with that scope.
429 "Too many refused access tokens came from this address": wait the seconds it names. Each token also has its own allowance a minute.
"Confirm your email address before making an access token.": confirm your address first.
"This organization does not accept personal access tokens. Ask an administrator for a service account."

/help/api-testing/run-in-a-pipeline
/help/api-testing/cli-agent
/help/settings/integrations
/help/organizations/roles-and-permissions