Skip to content

Create an API token

POST
/auth/tokens

Creates an API token for your account. This response is the only time you see the token: only a hash of it is stored. If you lose it, revoke it with DELETE /auth/tokens/{id} and create a new one.

You have to be signed in with the session cookie. A request that authenticates with an API token gets 401, even if it also sends the cookie, so a leaked token can’t be used to create more.

A token acts with your account’s full permissions: scopes can be recorded on it, but they aren’t enforced yet. Set an expiry when you can.

object
name
required
string
>= 1 characters <= 100 characters
Example
CI deploy bot
expires_at
string format: date-time
nullable
scopes

Capability codes to record on the token. They aren’t enforced yet: whatever you put here, the token can do everything your account can.

Array<string>

The token was created. Its value is in token.

object
id
required
string format: uuid
name
required
string
scopes
required
Array<string>
created_at
required
string format: date-time
expires_at
string format: date-time
nullable
last_used_at
string format: date-time
nullable
token
required

The token itself. Save it now: it isn’t returned again.

string
Example
aa_pat_K7eHs0bdQ9XR8h0g7y4mR0aZ2lY1pX5N

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}