Personal Access Tokens

Personal Access Tokens (PATs) are workspace-scoped bearer credentials for programmatic access to the Hiveship REST API. Each token belongs to one user, one workspace, and one or more per-entity scopes — issues, projects, comments — split by read and write. Available on the PRO, TEAM, and ENTERPRISE plans (see pricing).

Issuing a token

1. Open Workspace settings → API Tokens in the dashboard.
2. Click Create token. Give it a name (used only to identify the token later — "CI deploy script", "Personal CLI").
3. Pick scopes. Be specific — a CI script that only creates issues should get write:issues, not every scope.
4. Copy the token immediately. The plaintext is shown once and never stored — close the dialog and it's gone. If you lose it, revoke and issue a new one.

Token format

Tokens look like hsp_clu123_abcdef0123456789… — a hsp_ prefix, your user id, and a 64-hex-character secret. Send the full string as a Bearer header:

curl https://hiveship.app/api/workspaces/clx.../issues \
  -H "Authorization: Bearer hsp_clu123_abcdef0123456789..."

The user id is embedded in the prefix so server-side auth is a single database lookup; the secret is bcrypt-hashed and never returned after issuance. Don't mix the bearer header with the hiveship_access cookie on the same request — the server rejects ambiguous credentials.

Scopes

Six scopes cover the three publicly-callable entities:

Workspace settings, billing, members, and the PAT management surface itself are not PAT-callable — those routes require the cookie session that the web app holds. The separation keeps the human-operated administration surface distinct from third-party tooling.

Rate limits

Two limits apply per token:

• Global per-IP throttle — 60 req/min, the same default that protects every endpoint.
• Per-token sliding window — 1,000 req/min on PRO + TEAM, 5,000 req/min on ENTERPRISE. Counters are global, not per-endpoint; a burst of 200 issue creates eats the same budget as 200 project reads.

Every PAT-authenticated response carries the current state of the per-token window:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset:     1717250060   # unix seconds
Retry-After:           30           # only on 429

Honour Retry-After when you see a 429. The server is also watching for sustained over-limit behaviour — repeated 429s shorten the per-token reset window.

Rotation + revocation

Tokens have no expiry by default — they work until you revoke them. Treat them like passwords:

• One token per integration so revoking one doesn't break the others.
• Store the plaintext in a secret manager (1Password, Doppler, Vault) — never in git.
• Rotate proactively at least once a year, and immediately if you suspect exposure (leaked log, mistaken commit, departing team member who knew it).

Revoke from the same Workspace settings → API Tokens page. Revoked tokens stop authenticating immediately; the row stays in the list (line-through, "Revoked" chip) for forensics. There is no in-place rotate today — revoke and issue.

Cross-workspace boundaries

A token carries its issuing workspace's id in its bearer prefix and the server enforces two things on every request:

1. The URL's :workspaceId path parameter must match the token's issuing workspace.
2. The user who owns the token must still be a member of that workspace. If they were offboarded, every previously-issued token of theirs stops working at the next request.

A stolen token cannot pivot to another tenant — the user wouldn't be a member there. When you offboard a team member, you don't need to manually revoke their tokens; removing their workspace membership invalidates them.

Per-user cap

Each user can hold up to 20 active tokens per workspace. Revoke unused tokens to free slots — the limit exists to make "leaked one, revoked one, issued another" the natural pattern rather than a hoard-everything anti-pattern.

Audit trail

Every token operation (create, revoke) writes an audit-log row visible to workspace admins. Token plaintext is never logged; only the token name, scopes, and the last four characters of the secret (tokenHint) survive. Use the audit explorer to answer "who issued this token, and when did they revoke it?"

Live reference

The PAT management endpoints (GET / POST / DELETE /api/workspaces/:wId/api-tokens) are documented inside the live Swagger UI under the Personal Access Tokens tag. Open Swagger UI and try-it-out with a cookie session.

The PAT management surface itself is cookie-only — you cannot use one PAT to mint another. This is intentional: human-operated credential issuance shouldn't be reachable via stolen machine credentials.