Authentication

Every Coauthor request requires an authentication token. The token identifies the user or bot the agent represents. It also names the documents that the agent may reach, and what it may do there. Your backend signs the tokens with an access key of your environment.

Note

Prerequisites

You need two values from your environment. In the Customer Portal, open Cloud environments, then your environment:

The environment ID. Every token names it.
An access key. It signs the tokens. Create one on the Access credentials tab. See Access key.

How tokens work

A session is the agent’s work on one document, from the moment it is opened until it is closed, and not a real-time collaboration session. See Sessions in the API reference.

There are three tokens:

The backend token. Your backend signs it. It grants access to the documents specified in the token, so keep it on machines that you control. A developer tool such as Claude Code also holds a backend token, and opens its own sessions.
The session token. Your backend gets it when it opens a session. It works for that one session only, so give this token to your own agent.
The login server token. Your login server issues it to a chat app, such as ChatGPT or claude.ai, for one user. It works only over MCP.

Sign a backend token

A backend token is a JSON Web Token. Your backend signs it with the access key, the same way as the token of your token endpoint. Keep the access key on your server: anyone who holds it can sign tokens for your environment.

This token lets a review bot open a session on the pricing document, read it, and add its edits as suggestions:

{
	"aud": "<your environment ID>",
	"iat": 1791972000,
	"exp": 1791975600,
	"user": { "id": "review-bot", "name": "Review bot" },
	"auth": {
		"toolkit": {
			"permissions": [ "sessions:open", "sessions:read", "sessions:apply", "sessions:close" ],
			"documents": { "pricing": {} },
			"mode": "suggest"
		}
	}
}

The token says who it is for, which documents it reaches, what it may do, and whether its agent may only suggest. A token can also reach all documents of your environment, which an uploaded document or a snapshot needs. Permissions shows what each job needs. Backend token in the API reference describes every field.

How long a token works

A backend token works until it expires, and never longer than 24 hours after your backend signed it. A session token stops when its session ends, or when the backend token that opened the session expires. So sign that backend token for at least as long as the session lasts.

Revoke a token

A session token: close its session. The edits that nobody applied are discarded. The agent can still read, but it can no longer write. You cannot revoke a session token on its own.
Backend tokens: in the Customer Portal, remove the access key that signed them. This stops every token of that key, so switch your backend to a new key first.
Chat apps: in your login server, turn off the user, or the chat app.

Next steps

Permissions shows what each permission allows, and the token for each common job.
Connect an agent shows how your agent uses a token to reach the documents.