Scopes and tokens
What a device token is, the access choices, how long a token lives, and how to keep and revoke one.
A token stands in for your password on one machine or in one agent. It can read your scenes, edit them, or also share them, and you can take it back at any time.
#Access choices
| Level | Scopes | Allows |
|---|---|---|
| Read only | scene:read | List, inspect, evaluate, read documents and contracts |
| Read and write | scene:read, scene:write | Everything above, plus edits, covers and indexing |
| Read, write and render | scene:read, scene:write, render | Read and write, plus pictures and films when hosted rendering is configured |
| Read, write and sculpt | scene:read, scene:write, sculpt | Read and write, plus paid sculpt generation and splitting |
| Read, write and share | scene:read, scene:write, share:write | Read and write, plus creating and revoking links |
| Full access | scene:read, scene:write, render, sculpt, share:write | All the capabilities above |
sculpt_object and segment_sculpt require sculpt, even with your own provider keys. get_sculpt only reads a sculpt that already exists, so scene:read is enough. Render, sculpt and share access are separate choices; one does not grant the others.
Every MCP tool declares the scope it needs. A call without it is refused with HTTP 403. The refusal says what the connection cannot do yet and how to get it: reconnect with that access, or make a token at that level here in Settings → Agents. The missing scopes stay in requiredScopes. The WWW-Authenticate challenge names every scope the call needs plus the ones the token already holds, so a client that signs in again with exactly those keeps its existing access. The consent page offers exactly the set a client asks for, never more, and still starts on the least access. New tokens get read and write unless you choose otherwise. A terminal signed in with puni auth login gets read and write too, or sharing when it asks with --scope share; signing in never grants rendering or sculpting. A token made before rendering existed never gains it on its own; make a new one.
#Lifetime
| Thing | Lives for |
|---|---|
| The code you approve in the browser | Ten minutes |
| The device token | Thirty days |
| Each session the token opens | Five minutes, renewed on every request |
Revoking a token ends its sessions immediately, not at their next renewal.
#Tokens from the sign-in door
ChatGPT, Claude.ai and Claude Desktop get their token through Puni's own sign-in door instead of a paste. It is the same kind of token, with the access you chose on the consent page, plus a refresh grant so the client can stay connected. Settings → Agents → Connected lists them; Disconnect revokes the token and the grant together.
| Thing | Lives for |
|---|---|
| The access token the client sends | One hour |
| The refresh grant that renews it | Thirty days, extended while the client keeps renewing |
| A renewal answer the client did not keep | One minute |
Each renewal replaces both the access token and the refresh token. Sometimes a client presents the same refresh token twice: parallel tool calls each renew when the hour runs out, or a renewal is retried because its answer was lost. Within one minute of the first renewal, the repeat renews again and the connection stands. After that minute, an already-used refresh token ends the grant, and the client has to sign in again.
#Where a token lives
The command line keeps tokens per origin in ~/.config/puni/credentials.json, a file only you can read. PUNI_AUTH_TOKEN in the environment overrides the file and is never written to it. --auth-file points at another file.
Never paste a token into a command, a prompt, a scene description or a repository. The command line redacts tokens from its own output.
#What a token cannot do
A token cannot approve another device, delete a scene or your account, change your sign-in, or reach other people's scenes. Deleting a scene for good is the owner's alone, in Settings → Storage or the library's archived-scene menu, in a browser; no token, MCP tool or agent can do it, whatever its scopes. A token with scene:read can still read what the account holds and what deleting a scene would remove: those reads are the owner's own and change nothing. Agent tools never gain a shell, arbitrary network access, or the power to publish outside Puni.
Read Security and privacy for the rest of your account, or Connect Puni to make a token.
Was this useful?