Personal access tokens
Personal access tokens (PATs) are per-user API credentials. They authenticate as you and inherit your current role at request time. Use them for the CLI, exploratory scripts, and personal automation.
For shared service credentials that survive your departure from the org, use API keys instead.
PAT vs. API key
| Personal access token | API key | |
|---|---|---|
| Owner | One specific user | The organization |
| Role | Inherits the user's current role on every request | Fixed at creation, must be <= creator's role |
| Survives user removal | No, suspended/deleted with the user | Yes |
| Created by | The user themselves | An Admin |
| Recommended for | CLI, personal scripts, demos | CI/CD, integrations, scheduled jobs |
Creating a PAT
- Settings -> Profile -> Personal access tokens -> New token.
- Provide:
- Name — e.g.
laptop-cli. - Expiration — set as short as practical. PATs without an expiry should be the exception.
- Permissions (optional) — narrow the inherited role to a subset of permission strings if you want a least-privilege token.
- Name — e.g.
- Copy the secret immediately. It is shown once.
The token format is:
The first 10 characters are a non-secret prefix used to identify the token in lists and logs.
Authenticating requests
Same headers as API keys — both are accepted:
The server runs a bcrypt comparison on the presented secret against the stored hash. PAT authentication is a few milliseconds slower than API key authentication — fine for human-paced traffic, less suited to high-rate machine traffic (use an API key for that).
Permission re-evaluation
PATs do not snapshot a role. They re-evaluate on every request:
- If your role is downgraded, your PATs immediately have the new lower role.
- If your account is suspended or removed, every PAT you own stops working.
- If you change orgs, the PAT remains bound to the org it was created in.
This is the right behavior for a personal credential; it makes offboarding atomic.
Revocation
Revoke a PAT from the same settings page, or:
Revocation is immediate. There is no rotation; create a new PAT, switch to it, then revoke the old one.
Never put a PAT in a shared CI variable, a checked-in dotfile, or a screenshot. If you need a credential that survives offboarding, ask an Admin to create an API key.