Personal access tokens
A Personal access token (PAT) is a long-lived bearer token scoped to a subset of your account's permissions. PATs are the right credential for scripts you run as yourself: a quick report, a small integration, a tiny scheduled job that lives on your laptop. For production-scale automation, use a workspace API key instead — PATs are account-scoped and disappear when you leave the workspace.
TL;DR — Open Account → Personal access tokens. Generate a token, pick a scope set, set an expiry, copy the token once, revoke any time. Every operation is audited; expanding a PAT's scopes past read-only requires a step-up.
When PATs are the right tool
| Field | What it does | Accepted values / default |
|---|---|---|
| Ad-hoc scripts you run as yourself | A weekly report you ssh-into a server to run. | PAT. Short scope set; short expiry. |
| Small single-developer integrations | A laptop-side syncing script. | PAT. Stable scope; expiry forces rotation. |
| Production backends | A service that automates payroll, year-end, etc. | Workspace API key. Survives team changes. Audited at workspace level. |
| Directory sync | Microsoft Entra ID / Okta → AxisSynapse. | SCIM bearer token. Wired into the IdP connector. |
| Webhook signature verification | Outbound deliveries. | Webhook signing secret. One per subscription. |
Generate a PAT
Open Account → Personal access tokens
The page lists every PAT you've issued with its label, scopes, last-used timestamp, and expiry.
Click "Generate token"
A drawer asks for label, scopes, and expiry.
Pick a Label
Free text. Used in your audit feed for context.
Pick the scopes
Tick from the scope list. Scopes are read-only / read-write per module. Start with the smallest scope set that satisfies your script.
Pick the expiry
No expiry / 30 days / 90 days / 180 days / 365 days / custom. Short expiry is the security best practice; the form defaults to 90 days.
Copy the token
The token is shown ONCE. Paste it into your secret store (or your script's local
.env) immediately.
Rotate or revoke
Open the PAT's row
The row shows the last-used timestamp; if a token has been quiet for weeks, consider whether you still need it.
Rotate
Generates a fresh token with the same label + scopes + expiry. Old token is invalidated immediately — no overlap window for PATs.
Revoke
Immediately invalidates the token. Consumers begin returning
API_KEY_INVALID.Elevation (scope expansion)
Increasing a token's scope past read-only requires a fresh step-up. Reducing scope (or revoking) doesn't.
Scope catalogue
The public scope list is the same one shown on the workspace API key form. Each scope is named after the customer-facing API surface.
| Field | What it does | Accepted values / default |
|---|---|---|
| platform:read | Read workspace metadata, security policy state. | Useful for inventory / compliance scripts. |
| platform:write | Write workspace metadata, change security policy. | Step-up on elevation. Use sparingly. |
| hcm:read / hcm:write | HCM data: employees, payroll, time-off, benefits, performance, etc. | Per-employee, payroll, year-end, etc. read-only common; write reserved for automation. |
| eeo:read / eeo:write | EEO case data. | Read-only for reporting; write reserved for case automation. |
| elr:read / elr:write | ELR grievances, accommodations, FMLA, etc. | Same pattern. |
| inventory:read / inventory:write | Items, transfers, counts. | Same pattern. |
| fa:read / fa:write | Fixed-assets data. | Same pattern. |
| procurement:read / procurement:write | Procurement requisitions, POs, approvals. | Same pattern. |
| ethics:read | Ethics intake data (read-only). | Write operations are restricted to in-app surfaces. |
Every field, explained
| Field | What it does | Accepted values / default |
|---|---|---|
| Label | Free-text identifier. | Up to 100 characters. |
| Scopes | Permissions the token carries. | One or more scope strings; multi-select. |
| Expiry | When the token auto-revokes. | No expiry / 30d / 90d (default) / 180d / 365d / custom date. |
| Last used | When the token last authenticated a request. | Updated near-real-time. Use to spot stale tokens. |
| Step-up on elevation | Scope expansion past read-only. | Fresh MFA proof required. |
| Rotation | Generate a new token with the same metadata. | Old token immediately invalidated. No overlap. |
What appears in the audit log
ACCOUNT_PAT_CREATED— token issuance. Carries the label and scope set.ACCOUNT_PAT_REVOKED— token revocation, manual or auto-revoked by expiry.
Scope elevations and rotations also emit the same _CREATED /
_REVOKED pair, with the rotation paired as a single transaction in
the row metadata.
Common gotchas
- "I lost my PAT." Cannot be retrieved. Rotate (replaces the value), revoke, or generate a new one with the same scopes.
- "My script breaks intermittently." Check the last used timestamp on the PAT — if it isn't updating during the failure window, the script isn't actually sending the token (auth header issue). If it is updating, the failures are downstream.
- "My PAT expired during a long-running job." Use a workspace API key with overlap-on-rotation for long-running production jobs; PATs are designed for short-lived scripting.
- "I want to share a PAT with a teammate." Don't. Tokens are bound to your account; if your teammate needs the same access, they generate their own.
- "A PAT keeps being used after I leave a workspace." Token is revoked when your account is deactivated. If your old account is still active, revoke the PAT explicitly.
Troubleshooting
| Error code | What it means | Fix |
|---|---|---|
| API_KEY_INVALID | Token unknown or expired. | Rotate or regenerate. |
| API_KEY_SCOPE_INSUFFICIENT | Endpoint requires a scope the token doesn't carry. | Elevate (step-up) or generate a new token. |
| API_KEY_EXPIRED | Token reached its expiry. | Generate a new one. |
| API_KEY_STEPUP_REQUIRED | Scope elevation requires a fresh step-up. | Complete the step-up prompt. |
Related