Skip to content

Personal access tokens

A personal access token (PAT) is the credential a script uses to talk to the Priority.vote API on your behalf. Tokens start with the prefix pv_pat_ followed by a random secret and act as a Bearer token on any endpoint that accepts them.

Creating a token

  1. Sign in to Priority.vote.
  2. Open Account settings → API tokens.
  3. Click Create token.
  4. Give the token a descriptive name (it shows up in the audit logbook).
  5. Pick at least one scope:
  6. read — list and read initiatives.
  7. write:initiatives — create and update initiatives (implies read).
  8. Optionally restrict the token to specific backlogs. Default: all your backlogs (current and future).
  9. Pick an expiry: 30 days, 90 days, 1 year, or never.
  10. Click Create. The full token value is shown exactly once — copy it into your secret store now. The interface will never show it again.

Using a token

Send it as a Bearer header:

GET /api/v1/backlogs/{backlogId}/initiatives HTTP/1.1
Host: priority.vote
Authorization: Bearer pv_pat_abcdef…

Rotating a token

There is no single "rotate" action. Issue a new token, switch your adapter to it, verify, then revoke the old one. Both tokens can coexist — the per-user limit is sized to allow at least one overlap.

Revoking a token

Account settings → API tokens → Revoke. Effect is immediate; the next request with that token returns 401 invalid_token.

What PATs cannot do

  • They cannot reach /api/v1/auth/* endpoints (sign-in, sign-out, password reset).
  • They cannot create or revoke other tokens — PAT management is interactive only.
  • They cannot bypass row isolation — a token can only read or write data the owner could.

Logbook trail

Every state-changing request authenticated with a PAT writes a logbook entry tagged with the token's name (e.g. via 'jira-sync' token). The token name is captured at write time, so the audit trail survives even after the token is deleted.

Limits

  • Up to 10 active tokens per user (configurable by the operator).
  • Token value carries ≥128 bits of entropy from random_bytes.
  • The raw value is sha-256-hashed at rest. Anyone with database access still cannot recover your token from the hash.