# 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](authentication.md).

<a id="what-each-permission-allows"></a>

## What each permission allows

| Permission       | Lets the token                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `sessions:open`  | Open a session.                                                                                               |
| `sessions:read`  | Check the state of a session, read the agent’s draft, and read an uploaded document. Use the tools that read. |
| `sessions:tools` | Call the tools itself. Each tool also needs `sessions:read` or `sessions:apply`.                              |
| `sessions:apply` | Apply the edits to the document, and change the options of a session. Use the tools that edit.                |
| `sessions:close` | Close a session.                                                                                              |

Unknown permission values are accepted but grant no access. A session token needs no permissions: it works for its own session. The [API reference](https://help.cke-cs.com/toolkit/v1/docs#section/Authentication) lists every permission, and the permission that each call and tool needs.

<a id="permission-examples"></a>

## Permission examples

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.

<a id="a-person-works-in-claude-code"></a>

### A person works in Claude Code

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.

```json
{
	"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"
		}
	}
}
```

<a id="your-backend-runs-your-agent"></a>

### Your backend runs your agent

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.

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

<a id="your-agent-only-proposes"></a>

### Your agent only proposes

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.

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

<a id="fixed-edits-without-a-model"></a>

### Fixed edits without a model

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

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

<a id="recommendations"></a>

## Recommendations

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.

<a id="next-steps"></a>

## Next steps

* **[Authentication](authentication.md)** shows how to sign a token, how long it works, and how to stop it.
* **[API reference](reference.md)** links to the full API reference, with the permission that each call and tool needs.

---

Full index of the Cloud Services documentation: [llms.txt](../../../../llms.txt)