Personal Access Tokens

A Personal Access Token (PAT) is a long-lived, named, revocable credential you mint from the app's Settings UI. It lets scripts, CLI tools, CI pipelines, and e2e test harnesses authenticate sync requests without going through the interactive Better Auth handoff.

Minting a token

Open Settings → Access Tokens.
Click New token.
Enter a descriptive name (required). Names help you identify tokens later — for example "CI pipeline" or "local script".
Optionally set an expiry date. Tokens without an expiry remain valid until you revoke them manually.
Review the scope selection. The current UI preselects the four narrow document/asset authoring scopes; Full access is a mutually exclusive, explicit compatibility option.
Optionally choose Restrict to this workspace only. Always enable this for a local coding agent or other single-workspace automation client.
Click Create.

Scopes

The generic token form defaults to documents:read, documents:write, assets:read, and assets:write. Pick only what the caller needs:

Scope	Grants
`documents:read`	List/read/search documents; poll the document change cursor; read versions and checkpoint projections through the Automation API.
`documents:write`	Create, replace, soft-delete, move, and restore documents, plus create authoring checkpoints.
`assets:read`	List usage/assets and download encrypted assets through the opaque Assets API. Also permits the ownership-checked salt metadata read needed for local asset keys.
`assets:write`	Upload a new asset or create an empty folder marker. It does not permit rename, delete, batch delete, or replace.
`agent:invoke`	Call the assistant and inline-AI ingress on `agent-server`; add it to an MCP PAT only for `ask_zudo_agent`.
`full`	Every narrow scope plus the wider compatibility surface. It is not the local-agent default.

The server mint endpoint still defaults an omitted scopes field to ["full"] so pre-scoped clients retain their old behavior. The app UI does not silently omit it: it submits the visible narrow default unless the user chooses Full access.

Mint a narrow-scope token for an automation client so a leaked credential is confined to what that client actually needs. The guided Settings → Local AI Agent MCP workflow always creates an exact four-scope, workspace-bound PAT; use the generic form to add agent:invoke when cloud-agent delegation is required.

Workspace binding

A token can optionally be bound to a single workspace at mint time. A workspace-bound token is rejected before another workspace is looked up, so a leaked token cannot use the response to confirm which other workspace IDs exist. Automation routes use typed NOT_FOUND; other gated route families may use a generic forbidden response.

Local Agent Authoring treats binding as mandatory: one stdio MCP process exposes one ZUDOTEXT_WORKSPACE_ID, and its guided token is bound to that exact id.

The one-time reveal

Warning

The raw token value is shown exactly once, immediately after creation. Copy it now — it cannot be displayed again. If you lose it you must revoke the token and mint a new one.

The token list page shows metadata only (name, scopes, workspace binding, creation date, last used, expiry, revocation status). The raw value is never shown again. The Local AI Agent flow embeds it only in its one-time generated config and discards that in-memory reveal when Settings closes or the user chooses Discard one-time config; discarding does not revoke the token.

Using the token

Include the token in the Authorization header of any request to the sync API:

Authorization: Bearer <your-token>

Typical contexts:

Context	How to use it
CI / CD pipeline	Store the token as a secrets/env variable; inject it as the `Authorization` header in sync API calls.
CLI scripts	Pass it as a header in `curl` or your HTTP client of choice.
E2E test harness	Supply it via the test environment configuration so headless tests can authenticate without an interactive sign-in.
Automation clients	Present a workspace-bound narrow PAT to the Automation/Assets APIs or local MCP server.

Bearer authentication is shared, but authorization still follows the token's scopes. A narrow document/asset token cannot use workspace administration, devices, billing/subscription, token management, or publish routes. A PAT can never mint, list, or revoke sibling tokens; those operations require an interactive sign-in session even when the PAT holds full.

Security boundary — identity only, not decryption (with one opt-in exception)

Note

A PAT is an identity and transport credential only. It proves who you are and authorizes the server to accept pull/push of your encrypted blobs, but by itself it grants zero decryption capability. Your note content is protected by a workspace key derived from your passphrase — a key that never crosses the wire as part of ordinary PAT use, and is never touched by the token minting/listing/revoking system. Possessing a PAT alone gives no path to that key.

What this means in practice:

Confidentiality is preserved for ordinary PAT use. A leaked PAT cannot read your note content, no matter how long the attacker holds it, as long as no key session has been opened with it. The encrypted blobs stored on the server remain opaque without the passphrase-derived workspace key.
Integrity and availability follow the selected scopes. A leaked documents:write token can mutate or soft-delete documents once paired with a valid key session; assets:write can consume quota with new encrypted assets; agent:invoke can spend AI turns. A full token retains the much wider legacy impact. Least privilege and workspace binding materially reduce the blast radius.
A leaked PAT cannot mint, list, or revoke other tokens. Token management requires your interactive sign-in session — not a PAT — so a leaked credential cannot escalate laterally to mint siblings or cover its tracks.

Revoke a token as soon as you suspect it has been exposed.

The key-session exception (Automation API)

Caution

The Automation API — the document surface AI agents use — carves out a deliberate, narrow exception to the zero-decryption boundary above. Before an automation client can read or write plaintext documents, it must explicitly open a key session by posting your workspace's three derived decryption keys to the server once. This is opt-in per session, never a standing PAT capability:

Consent-gated. The client only reaches this step after an explicit consent step makes clear that keys are about to leave the device for this session.
Scoped. The keys are usable only through routes the presenting token's own scope covers (documents:read/documents:write) — a session opened with a narrow-scope token doesn't grant more than that token could already do.
TTL'd. The server holds the decryption-capable keys in memory only (a Durable Object instance, never written to disk) for at most one hour, after which they're evicted automatically even if the session is never explicitly closed.

A PAT that has never been used to open a key session keeps the full zero-decryption guarantee above. One that has, for the duration of that session, trades a bounded, explicit slice of confidentiality for the ability to automate reading and writing documents — see the Automation APIfor the full mechanics.

Asset automation does not use this exception. Asset keys remain non-extractable in the local MCP process; the Worker sees opaque tokens and encrypted envelopes. An explicit assets:read PAT may fetch the workspace salt after workspace-binding and ownership checks, even without an active document subscription, but that metadata read neither opens a key session nor authorizes any document route.

Listing tokens

Open Settings → Access Tokens at any time to see all your tokens. Each row shows:

Column	Description
Name	The label you chose at creation
Created	When the token was minted
Last used	When the token was last accepted by the server (updated asynchronously)
Expires	Expiry date, or "Never"
Status	Active, Expired, or Revoked

Revoked tokens remain listed so you can see when and that they were revoked. The raw token value is never shown in the list.

Revoking a token

Click Revoke on any active token in Settings → Access Tokens. Revocation:

Takes effect immediately for all new REST requests and new sync WebSocket connections.
Does not terminate an already-open WebSocket session. A sync session established before revocation continues until it closes naturally (app quit, network drop, or session timeout). If you need to ensure a session is cut off immediately, the only reliable path is to close the app.

Caution

If you believe a token has been compromised, revoke it immediately, then check your cloud workspace for unexpected changes and your AI usage for unusual quota consumption.

Token expiry

Tokens with an expiry date stop working automatically when the expiry time passes — you do not need to revoke them manually. Expired tokens still appear in the list with an "Expired" status and continue to show their last-used timestamp.

If a script or CI job stops authenticating unexpectedly, check whether the token it uses has expired and mint a replacement if so.