Create an Agent Access Token
An Agent Access token lets a client authenticate to Gavana without your browser session. Tokens are named, scoped, and individually revocable. New tokens start with all eight available permissions and do not expire unless you choose a custom expiry.
In the Gavana interface these are labelled Personal Access Tokens. “Agent Access token” is the same credential — the term used in the API, the CLI, and this documentation. If you are looking for the screen, open the account menu and choose Personal Access Tokens.
When you need one
You do not need a token for:
- ChatGPT, or any remote MCP client that supports OAuth — those use the hosted MCP endpoint with browser sign-in.
- Interactive CLI use —
gavana auth loginopens a browser and stores a revocable OAuth token for you.
You do need one for:
- The local stdio MCP server (Claude Desktop, Cursor, and other clients that launch a local process).
- Unattended automation — CI, a cron job, a backend service.
- Direct Canvas API calls from your own code.
Steps
Sign in to Gavana
Sign in at app.gavana.ai as the account whose canvases the agent should reach. A token acts as that account.
Open Personal Access Tokens
Open the account menu and choose Personal Access Tokens.
Name the token for one client on one device
The name is not decoration. It is written into node and activity provenance, so when you review a canvas later you can tell which client made which change — without trusting a name the caller supplied at request time.
Use one token per client per machine, named accordingly:
Claude Code · MacBook Air
Claude Desktop · Studio iMac
Codex · CI runner
Cursor · work laptopNames are limited to 80 characters and default to This device.
Keep the default expiry or choose a custom one
Never is the default: the token keeps working until you revoke it. Choose Custom only when this is a temporary or less-trusted device; a custom expiry can be from 1 to 90 days and cannot be changed after creation.
Choose permissions
All eight permissions are selected by default so a new token can use the full Gavana workflow. Reduce them when a client should have a narrower boundary. The eight permissions are:
| Scope | Interface label | Grants |
|---|---|---|
canvas:read | Read canvases | Read canvas graphs, nodes, connections, and revisions |
canvas:write | Change canvases | Create, update, move, resize, and delete nodes and connections |
asset:read | Read assets | Read asset references and metadata |
element:read | Read Elements | List Elements and collections, and read exact immutable Element revisions |
element:write | Manage Elements | Create, revise, organize, archive, restore, and delete Element collections |
image:generate | Generate/upload images and run Recipes | Generate and edit images, privately upload local raster inputs, and start any Recipe — including text-only Recipes |
video:generate | Generate videos from prompts and frames | Discover connected video models and start video generation |
job:manage | Observe and cancel Runs | Poll, wait for, and cancel shared Runs and Jobs |
Copy the token
The token is shown exactly once. Copy it straight into the client’s private configuration or your secret store — not into a note, a chat message, or a repository.
Tokens look like cba_ followed by a UUID, a dot, and a 43-character secret. If you lose it, revoke it and create another; there is no way to retrieve it.
Permission dependencies
Some permissions cannot work alone, and Gavana enforces the dependencies in two places — the picker selects them for you, and the server rejects an invalid combination if you call the API directly.
| Selecting… | Also requires |
|---|---|
canvas:write | canvas:read |
element:write | element:read |
image:generate | canvas:read, canvas:write, asset:read |
video:generate | canvas:read, asset:read |
Note that video:generate does not require canvas:write. Video generation can produce a downloadable Job output without writing a native video node to a canvas.
The dependency also runs in reverse when you deselect. Clearing canvas:read clears canvas:write, image:generate, and video:generate with it. Clearing canvas:write clears image:generate. Clearing asset:read clears both image:generate and video:generate. Clearing element:read clears element:write. The picker will not leave you holding a permission that cannot function.
job:manage has no dependencies and nothing depends on it — see below for why you almost always want it anyway.
Why job:manage matters more than it looks
Without job:manage, a token can start generation but cannot poll it, wait for it, or cancel it. Every CLI and MCP path that waits for a result by default will fail at the waiting step.
You have two workable configurations:
Normal (recommended). Include job:manage. The client starts work and waits for durable handles in the same call.
Start-only with a webhook. Omit job:manage, start work with --no-wait, and supply a signed webhook so Gavana calls you back at the terminal state. Gavana’s worker keeps the Run moving after your process exits.
A start-only token stays revocable while Gavana’s worker is running the job. If the token expires or is revoked before the Run finishes, Gavana stops the Recipe with delegation_revoked and sends its signed failed callback. Revocation is not silently ignored mid-run, and it is not a way to cancel without the callback firing.
MCP intentionally omits webhook secrets from tool arguments, so the webhook path is an API and CLI feature. See Webhooks.
Scope recipes
| Client and intent | Scopes |
|---|---|
| Review-only agent, no changes | canvas:read, asset:read, element:read |
| Structure-building agent — notes, sections, connections, workflow scaffolding | canvas:read, canvas:write, asset:read, element:read |
| Element librarian | element:read, element:write |
| Full creative agent | canvas:read, canvas:write, asset:read, element:read, element:write, image:generate, job:manage |
| Video work as well | add video:generate |
| Backend service using webhooks instead of polling | canvas:read, canvas:write, asset:read, image:generate — no job:manage |
What the token can and cannot do
A token acts as your account, limited to its scopes. It reaches the canvases you can reach.
It cannot:
- Escalate its own scopes.
- Create other tokens.
- Read or change your AI provider credentials.
- Change its scopes or expiry after creation. Create a replacement if either needs to change.
- Keep working after a custom expiry passes.
Gavana holds at most 20 active tokens per account. Expired custom-expiry tokens are cleaned up when you create a new one.
Revoking
Open Personal Access Tokens and revoke the token you no longer trust. Revocation takes effect on the next request against that token. Because tokens are per-client, revoking one does not disturb your other connected clients.
Revoke immediately if a token was pasted into a chat, committed to a repository, screenshotted, or used on a machine you no longer control. Rotating is cheap; a leaked token that keeps working is not.
The list also shows each token’s last used time. A token you do not recognise, or one that has never been used, is a candidate for revocation.
Handling the token safely
- Never paste a literal
cba_…value into a shell command. Use the stdin prompt shown in Install the CLI so it never reaches shell history or the process table. - Store it in the client’s private configuration or your platform secret store. On macOS, the CLI’s browser login puts its token in Keychain automatically.
- Keep it out of the places listed in the safety contract — chat, URLs, logs, screenshots, and repositories.
- If a token stops working unexpectedly, check whether the Gavana account’s own session was revoked: the API returns
The delegated Firebase session was revoked. Create a new agent token.Signing out of Gavana everywhere invalidates tokens created from that session.
Compatibility
The cba_ token prefix, the CRAFTBOARD_* environment variables, and the craftboard command aliases all remain supported. A token created today works with both the GAVANA_AGENT_TOKEN and CRAFTBOARD_AGENT_TOKEN variable names.