Personal Access Tokens

Personal Access Tokens (PATs) are user-bound credentials that let you authenticate Assumetr API calls from scripts, CI/CD pipelines, and local tooling without sharing your login session.

PATs vs. API Clients

PATs are owned by a specific user and inherit that user's permissions. API Clients are org-level machine principals with explicit scope grants. Use PATs for personal automation; use API Clients for shared service accounts.

Creating a PAT

1. Go to Settings → Preferences in your Assumetr dashboard.
2. Scroll to the Personal Access Tokens section.
3. Click + New token.
4. Enter a descriptive name (e.g. ci-pipeline, local-dev) and choose an expiry date.
5. Click Create token.

Copy the token immediately. It is displayed only once and cannot be retrieved again. If you lose it, revoke and create a new one.

Expiry is mandatory

Assumetr does not allow permanent (non-expiring) tokens. The maximum lifetime is 365 days. Plan for rotation.

Using a PAT

Include the token as a Bearer token in the Authorization header:

curl https://api.assumetr.com/v1/user/pats \
  -H "Authorization: Bearer pat_a1b2c3d4..."

PATs are accepted on any Assumetr API endpoint that supports bearer authentication. The request runs with your user's current permissions.

Token Format

Part	Example	Description
Prefix	pat_	Identifies the credential class
Body	a1b2c3d4... (64 hex chars)	Cryptographically random
Display prefix	pat_a1b2c3	Shown in the token list (first 8 chars)

The full token is 68 characters long. Store it as you would a password — in a secret manager, CI/CD secret variable, or .env file excluded from version control.

Revoking a PAT

1. Go to Settings → Preferences.
2. In the Personal Access Tokens section, find the token you want to revoke.
3. Click Revoke and confirm.

Revocation is immediate. Any automation using the token will receive 401 Unauthorized on the next request.

Token Lifecycle

State	Condition	API response
Active	Not revoked, not expired	Requests succeed
Expired	expires_at has passed	401 — re-create the token
Revoked	Manually revoked	401 — create a new token

Security Recommendations

• Use descriptive names. Include the system or purpose (ci-deploy, audit-export) so you know where a token is used.
• Set the shortest practical expiry. A 30-day token for a one-off task is better than a 365-day token.
• Rotate before expiry. Create the replacement token, update your secret manager, then revoke the old one.
• Never commit tokens to version control. Use CI/CD secret variables or secret managers.
• Review periodically. The token list in Preferences shows last-used dates — revoke anything unused.

API Reference

PATs are managed via three endpoints under /v1/user/pats. All require an active session token (Authorization: Bearer <session-jwt>) and a verified email address.

List PATs

GET /v1/user/pats

Returns all PATs for the current user. Plaintext tokens are never returned here.

Response 200:

{
  "pats": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "ci-pipeline",
      "token_prefix": "pat_a1b2c3d4",
      "status": "active",
      "created_at": "2026-04-01T10:00:00Z",
      "expires_at": "2027-04-01T10:00:00Z",
      "last_used_at": "2026-04-20T09:00:00Z"
    }
  ]
}

Create a PAT

POST /v1/user/pats
Content-Type: application/json

Request body:

{
  "name": "ci-pipeline",
  "expires_at": "2027-04-01T10:00:00Z"
}

Field	Type	Required	Constraints
name	string	✓	1–128 characters
expires_at	RFC 3339 datetime	✓	Must be in the future; max 365 days from now

Response 201:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "pat_a1b2c3d4...",
  "token_prefix": "pat_a1b2c3d4",
  "name": "ci-pipeline",
  "created_at": "2026-04-01T10:00:00Z",
  "expires_at": "2027-04-01T10:00:00Z"
}

WARNING

token is returned only once. Store it immediately.

Error codes:

Status	Code	Cause
400	validation_error	Missing or invalid name / expires_at (past date)
422	expiry_too_far	expires_at exceeds 365 days

Revoke a PAT

DELETE /v1/user/pats/{patID}

Immediately revokes the token. Subsequent requests using the token receive 401.

Response 204: No content.

Error codes:

Status	Code	Cause
404	not_found	Token does not exist or belongs to a different org
403	forbidden	Token belongs to a different user
409	already_revoked	Token was already revoked