Permissions

Permissions decide what a backend token may do in a session: open it, read the document, edit it, and close it. Your backend puts them into the token when it signs it. To sign one, see Authentication.

Unknown permission values are accepted but grant no access. A session token needs no permissions: it works for its own session. The API reference lists every permission, and the permission that each call and tool needs.

These examples show tokens configured for four common use cases. Each token also names the documents that it reaches, and whether its agent may only suggest.

The agent opens its own sessions, so the token needs all five permissions. Sign it for one person, with only the documents that this person may edit in your application. That person becomes the author of the agent’s suggestions. Let the agent edit directly if the person may edit without review.

{
	"user": { "id": "emma", "name": "Emma Brown" },
	"auth": {
		"toolkit": {
			"permissions": [ "sessions:open", "sessions:read", "sessions:tools", "sessions:apply", "sessions:close" ],
			"documents": { "pricing": {}, "q3-report": {} },
			"mode": "suggest"
		}
	}
}

Your backend opens the session, gives your agent the session token, then applies the edits and closes the session. It does not call the tools itself, so it needs no sessions:tools. For a chat, let the agent only suggest. For a job that people check later, let it edit directly.

{
	"auth": {
		"toolkit": {
			"permissions": [ "sessions:open", "sessions:read", "sessions:apply", "sessions:close" ],
			"documents": { "pricing": {} },
			"mode": "suggest"
		}
	}
}

Coauthor writes nothing into the document. Your backend reads the agent’s draft, and your application shows it. For a snapshot, the editor in the browser applies the draft. The token reaches all documents, as an uploaded document or a snapshot needs.

{
	"auth": {
		"toolkit": {
			"permissions": [ "sessions:open", "sessions:read", "sessions:close" ],
			"documents": { "*": {} }
		}
	}
}

Your backend calls the tools itself, so the token needs sessions:tools too.

{
	"auth": {
		"toolkit": {
			"permissions": [ "sessions:open", "sessions:read", "sessions:tools", "sessions:apply", "sessions:close" ],
			"documents": { "pricing": {} },
			"mode": "direct"
		}
	}
}

Give each token only what its job needs. A token reaches every document that it names, with every permission that it holds. So name only the documents that the job works on, and leave out the permissions that it does not use.

• Authentication shows how to sign a token, how long it works, and how to stop it.
• API reference links to the full API reference, with the permission that each call and tool needs.