Set Up Personal Access Tokens

Personal access tokens are the supported credential for external API usage. Use them for scripts, backend services, generated clients, and operational tooling.

PATs are sent directly as bearer credentials:

curl -H "Authorization: Bearer $PIX_PAT" "$API_BASE/v1/auth/tokens"

Do not use browser session cookies for external clients. Cookies are tied to interactive session behavior, refresh rotation, and browser CSRF protections.

Create A Token

Users can create PATs through POST /v1/auth/tokens while authenticated with an interactive browser session. A PAT, including an access JWT obtained by exchanging a PAT through the login endpoint, cannot create another PAT.

{
  "name": "nightly-import",
  "expiresAt": "2026-12-31T23:59:59Z",
  "organizationScopes": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "capabilityScopes": [
    {
      "capabilityKey": "JobsView",
      "maximumValue": "Allow"
    }
  ]
}

At least one organization and one capability scope are required. The user must have final, entitlement-capped PersonalAccessTokensUse in every selected organization. Capability keys and maximum values come from the server's code-owned permission catalog; unknown keys, duplicate scopes, invalid values, and PersonalAccessTokensUse itself are rejected. A capability maximum never grants permission: each request still uses the user's current membership, entitlement ceiling, resource permissions, and operational limits, then narrows that result with the token scopes.

Deployments can require a recent interactive authentication result before issuance. When enabled, sign in again and retry from the fresh browser session. The API returns the full token once. Store it in the secret manager for the calling system.

The legacy permissions request and response field is retained only for wire compatibility. It is not an enforced scope: non-empty request values are rejected, response values are empty, and no permission-string claim is added to an authenticated identity. organizationScopes and capabilityScopes are the authoritative credential ceiling.

List And Revoke

Use GET /v1/auth/tokens to list token metadata and its organization/capability scopes. The secret value is not returned after creation. Interactive listing and revocation remain available even when an organization entitlement transition makes PAT use unavailable.

Use DELETE /v1/auth/tokens/{tokenId} to revoke a token. Revocation takes effect on the next request, including requests made with an access JWT previously obtained from that PAT. Expiry, a missing account, or account deactivation also invalidates direct PAT and PAT-derived access-token authentication.

Every request reloads the token's current typed scopes and evaluates the user's current membership, ACLs, organization entitlement, and PersonalAccessTokensUse. Scope narrowing, membership or ACL removal, and tier downgrades therefore take effect on the next request. Restoring the same live authority reactivates an otherwise valid token without reissuing it. General API rate limiting is partitioned by PAT ID, so one automation credential does not consume the interactive-session or another PAT's bucket. Security-sensitive PAT permission denials are audit-attributed by user, token ID, organization, bounded failure reason, and request correlation; bearer secrets are never written to the permission audit payload.

Scalar

Scalar still supports bearer authentication. Paste a PAT into the bearer auth field when testing external-client behavior. If you are signed in through the browser session on the same API host, Scalar requests can also use the HttpOnly session cookie automatically.