API tokens

An application programming interface (API) token lets a script act on your behalf without your login. If it leaks, you delete the token and your password is unaffected.

They are under Security in the sidebar, then Tokens.

Create a token

Select New token and fill in three things.

New token on the Tokens page.

• Name. A label you will recognise later, like deploy-bot.
• Expiry. Between 8 days and 1 year. Every token expires, so rotate before it does.
• Permissions. Each resource kind gets NONE, READ, or WRITE. Give the token the least it needs. A monitoring script needs READ on what it watches and NONE on the rest. A script that only powers servers on and off needs WRITE on instances and nothing else.

Copy the token when it appears

We show the value once and keep only a hash of it. If you lose it, create a new token.

Workspace tokens

A workspace token belongs to the workspace rather than to you. When you create one you also pick a scope: the whole Workspace, or one Resource by its ID. Permissions, the one-time value, and deletion all work the same as a personal token.

Delete a token

Delete on the Tokens page stops it working immediately. Any script still using it is rejected on its next request. To rotate, create the new token, switch your script over, then delete the old one.

Use a token

Send it as a bearer token in the Authorization header. API authentication has request examples.