E005: Create API token (PAT)

POST /api/user/api-tokens

Generates a Personal Access Token (PAT) the caller can use for programmatic API access — CLIs, AI agents, third-party integrations. The plaintext token is returned once in the response and is never retrievable again; the backend stores only its SHA-256 hash. If the user loses the plaintext, they revoke it (E007) and create a new one.

Token format: pharus_pat_<32 base62 chars> (43 characters total). The branded prefix lets the auth middleware route between PAT and Firebase ID-token verification, and lets secret-scanners (e.g. GitHub on push) flag accidentally committed tokens.

Authentication

Authenticated route, no org membership required. Accepts either a Firebase ID token or another PAT.

Request

{
  "name": "my-cli",
  "orgId": "uuid (optional)",
  "expiresInDays": 30
}

• name — a human-friendly label (required, 1–255 chars). Shown in the tokens list.
• orgId — optional. If set, the PAT is bound to that org and the X-Org-Id header is ignored on subsequent requests. The caller must be a member of that org or the call returns 403.
• expiresInDays — optional. Token expiry is best practice for non-CI use; omit for a non-expiring token.

Response — 201 Created

{
  "token": {
    "id": "uuid",
    "userId": "uuid",
    "orgId": "uuid | null",
    "name": "my-cli",
    "tokenPrefix": "pharus_pat_",
    "lastUsedAt": null,
    "expiresAt": "2026-07-01T00:00:00.000Z",
    "revokedAt": null,
    "createdAt": "2026-06-01T00:00:00.000Z"
  },
  "plaintext": "pharus_pat_ABC123…"
}

Use the plaintext as Authorization: Bearer pharus_pat_… on subsequent API calls.

Errors

Status	Code	Trigger
401	forbidden	Missing or invalid bearer token.
403	forbidden	orgId provided and caller is not a member of that org.
422	validation_failed	Empty name, name > 255 chars, or expiresInDays out of range.

Maps to

W005.