Personal access tokens
Personal access tokens (PATs) are credentials you mint for programmatic platform access — your CLI, scripts, CI pipelines, third-party tools that act as you against the platform. Reach for one when you want to do something automated without typing a password each time.
PATs are different from service tokens. A service token represents a project, not a person — it's tied to the project's lifecycle, gets named like a server (api-prod-writer), and is what your application uses to talk to its own data plane. A PAT represents you — your operator identity, your roles, your org membership — and is what you use when you want a tool to run with your permissions.
1. One PAT belongs to one (org, project) pair
A PAT is bound to exactly one (org, project) pair, set when you create it. Both fields are immutable — you can't move a PAT to a different org or a different project after creation. If you operate across several projects (in the same org or across orgs), you create a PAT per project.
The constraint is deliberate, applied at two levels:
- Simplicity — most operators work in a single project most of the time. Multi-project tokens add permutation complexity (which scope applies in which project?) for a small fraction of users.
- Auditability — every authorised or denied call from a PAT lands in exactly one (org, project) audit ledger. "What did this PAT actually do last quarter?" resolves to a single-(org, project) query — no cross-project or cross-org join.
- Unambiguous entity names — with the bound project as the only namespace, unqualified entity names (a
userstable, anuploads/*object prefix) are unambiguous in every dimension.
You revoke a PAT explicitly (delete in Console or revoke via the CLI), or the platform auto-revokes it when your access is removed from the bound (org, project) pair. status: revoked with a reason of operator_revoked (you), org_membership_revoked (you lost the org), project_membership_revoked (you lost the project but kept the org), or ttl_expired (the token hit its TTL). No orphan tokens floating after access goes away.
2. Creating a token — Basic and Advanced
You create a PAT in the Console at your org's Settings → API tokens (or via the CLI). The configurator opens in Basic mode and toggles up to Advanced when you need more scoping dimensions.
Basic — name your token, pick the project it binds to, pick a tier (readonly, readwrite or admin), set a TTL. This is the 80% case: a CLI or CI token for one project.
Advanced — same required fields (label, project, tier, TTL), plus the power-user dimensions: a resource-class allowlist, per-resource entity allowlists, and a source-IP CIDR allowlist. Reach for Advanced when you want a token that can do strictly less than you can — narrow enough to share with a CI runner without giving it the keys to the kingdom.
Both modes require a project — project selection is a single-input requirement, not an Advanced affordance. Both modes produce the same underlying scope shape.
Both modes are available to every project, CIDR allowlisting included. Organisations can layer additional CIDR defaults via org policy.
3. The five scoping dimensions
A PAT's effective scope is the intersection of your live permissions and what you set on the token. Five dimensions compose:
| Dimension | What it restricts | Example |
|---|---|---|
| Tier | The scope tier — readonly, readwrite or admin; carried as scopeManifest.tier | A CI token at readwrite, no admin |
| Project | The bound project (required; exactly one) | Token bound to the staging project; calls against the production project get a 403 |
| Resource classes | The kinds of resources — database, object-storage, extension-data, and so on | Token allowed database reads but not object-storage |
| Collections | Specific entities within a resource class — tables, buckets | Token allowed database.users_public_view but not database.users |
| CIDRs | Source IP allowlist in CIDR notation (enforced at the edge) | Token usable only from 10.0.0.0/8 (your CI runner range); rejected at the edge from elsewhere |
The Project dimension is required and exactly one — Tier is required; the other three (Resource classes, Collections, CIDRs) are optional narrowings. Leave an optional dimension empty and the token doesn't narrow on that axis; it uses your full permissions in the bound project for that dimension.
Because every PAT is bound to a single project, the Collections allowlist scopes entity-level access within that bound project — database.users reads but not database.audit_log, say. There's no cross-project entity-name ambiguity to worry about (the bound project is the only namespace).
The intersection rule cuts both ways: if your operator perms tighten, the token's effective scope tightens with them. If you drop from admin to read-only on the bound project, every existing PAT scoped to that project drops with you. A PAT can never grant more than what its owner currently has.
4. PATs are immutable
Once created, a PAT's bound (org, project) pair, scope, label, and TTL all never change. There's no PATCH path, no "edit token" affordance. The mutation model is revoke and recreate.
Two reasons. Auditability — a token's entire history resolves to two records: one create, one revoke (or expiry). No mutation timeline to reconstruct, no "what scope did this token have last Tuesday at 14:30?" question. "What did this PAT do?" composes cleanly with the single-org audit ledger from the one-org-binding above. Simpler mental model — there's exactly one way to change a token's scope (mint a new one), so no skew between Console UI, CLI, and API.
The "create new similar" convenience in the Console pre-populates a fresh create form with the previous token's scope so rotating doesn't mean retyping — but the result is a new PAT with a new plaintext, not a mutation of the original. Capture the plaintext (§5), revoke the old token when you're ready.
5. The plaintext is returned once
When you create a PAT, the response carries the plaintext token — k9o_pat_<32 base62 characters> — exactly once. The Console shows it in a one-shot modal; the platform never persists the plaintext anywhere (no localStorage, no IndexedDB, no service-worker cache). Copy it to your password manager or CI secret store on the spot.
Lost a token? You don't recover it — you revoke the old one and mint a new one. The recoverability model is "store it now, or rotate."
6. Audit — every call lands in the bound (org, project) ledger
A PAT's entire audit footprint is three event types, all in the bound (org, project) ledger (and nowhere else):
| Event | When it fires |
|---|---|
data.write.auth.me.api_token.created | A PAT is created |
data.write.auth.me.api_token.revoked | A PAT is revoked — manually by you (reason: operator_revoked), by org-membership loss (org_membership_revoked), by project-membership loss (project_membership_revoked), or by TTL expiry (ttl_expired) |
data.read.auth.me.api_token.used | A PAT authenticates a call (sampled at high volume so the audit log doesn't flood) |
Because PATs are immutable, there is no patched event — and never any "what scope did this token have on date X?" question. A token's lifecycle is two ledger records: one created, one revoked. If a compliance reviewer asks "what did this PAT do last quarter?", the answer is one ledger query against one (org, project), walking forward from created to revoked with used events in between.
7. Lifecycle limits
- TTL — default 90 days; max 365. Tighter than service tokens (which can live up to 10 years), because a PAT carries your operator identity — a higher-stakes class than a project-scoped credential. On TTL expiry the platform emits a
revokedevent withreason: ttl_expired. - Active count — up to 25 active PATs per (operator, org) pair. If you're in three orgs you can have up to 75 PATs in total, distributed across them.
- MFA gating — if you have MFA enrolled, creating a new PAT triggers an MFA challenge (the same machinery that gates other consequential operator actions).
8. Errors you might encounter
The PAT family carries ten typed error codes. Most are self-explanatory once you know the dimensions above:
| Code | Means |
|---|---|
K9O_PAT_NOT_FOUND | The PAT ID doesn't exist, or isn't yours to see |
K9O_PAT_ORG_NOT_MEMBER | You're no longer a member of the org this PAT is bound to (memberships changed since creation) |
K9O_PAT_PROJECT_REQUIRED | At create time, you didn't pick a project (or picked more than one). Every PAT binds to exactly one project; the Console configurator enforces this in the UI, so you'll only see this from a CLI or direct API call with an empty or multi-entry projects field |
K9O_PAT_PROJECT_NOT_PERMITTED | The request targets a project other than this PAT's single bound project |
K9O_PAT_RESOURCE_CLASS_NOT_PERMITTED | The operation targets a resource class outside the PAT's scope |
K9O_PAT_COLLECTION_NOT_PERMITTED | The specific entity is outside the PAT's per-resource allowlist |
K9O_PAT_COLLECTIONS_REQUIRE_SINGLE_PROJECT | Defense-in-depth code; effectively unreachable in normal operation now that every PAT is single-project-bound. Retained for substrate edge cases |
K9O_PAT_CIDR_NOT_ALLOWED | The source IP isn't in the PAT's CIDR allowlist (caught at the edge before the request reaches the gateway) |
K9O_PAT_SCOPE_EXCEEDS_OPERATOR | At create time, the declared scope was wider than your current perms; the effective scope is the intersection. Fires only at create — PAT immutability means there's no patch path that could re-trigger this later |
K9O_PAT_LIMIT_EXCEEDED | You've hit the 25-active-per-org cap; revoke an older PAT or rotate |
See API → Conventions for the broader error envelope, and API → Auth for the surrounding authentication surface.
See also
- API → Auth — the broader authentication surface PATs live within.
- CLI — the primary tool that authenticates with PATs.
- Org scope — where you create and manage PATs in the Console.