# Scopes

> The permissions an API key or OAuth token can carry.

Source: https://docs.coline.app/authentication/scopes

Scopes limit what a credential can do. They never widen access: an OAuth token still can't reach anything its person can't open, and an API key can't reach another workspace. Ask for the fewest scopes you need.

A request that lacks a scope fails with `403` and `API_KEY_SCOPE_FORBIDDEN` (API keys) or `OAUTH_SCOPE_FORBIDDEN` (OAuth tokens).

## API key scopes

Chosen when the key is created.

| Scope                   | Allows                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `workspace.read`        | View workspace metadata and settings                                               |
| `taskboards.read`       | Read taskboards and tasks                                                          |
| `taskboards.write`      | Create, update and delete tasks                                                    |
| `calendar.read`         | Read calendars and events (OAuth tokens only in practice; see below)               |
| `calendar.write`        | Create and update events                                                           |
| `files.read`            | Read files and sheets, and download uploads                                        |
| `files.write`           | Create, upload, modify and delete files and sheets                                 |
| `apps.read`             | List installed apps and their manifests                                            |
| `apps.write`            | Install, configure and uninstall apps; push app versions with the CLI              |
| `apps.publish`          | Publish versions of the one app a Code project builds                              |
| `notifications.write`   | Send in-app and push notifications from an app                                     |
| `index.write`           | Add or update an app's documents in workspace search                               |
| `ambient.events.write`  | Publish an app's events to the workspace                                           |
| `ai.invoke`             | Call [Tab](/api/tab) and other AI endpoints, billed to the workspace's API credits |
| `upstream.checks.write` | Report check results on Upstream Change Requests                                   |
| `upstream.search.read`  | Search code in Upstream repositories                                               |
| `admin.read`            | View administrative data and audit logs                                            |
| `admin.write`           | Manage workspace settings and members                                              |

Calendar and message routes act for a person, so they refuse API keys with `USER_IDENTITY_REQUIRED` even when the key has the scope. Use OAuth for calendar and messages.

## OAuth scopes

Requested in the `scope` parameter of the [authorization request](/authentication/oauth) and shown on the consent screen. Clients created in the developer console get the scopes they ask for. Clients that register themselves (assistants) get every scope below except `ai.invoke` and `apps.*`, whatever they ask for.

| Scope                                 | Allows                                                                                                                                                         |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openid`, `profile`, `email`          | Sign-in and the [user info](/authentication/oauth#user-info) endpoint. The default when no scope is given                                                      |
| `workspace.read`                      | List the person's workspaces and read workspace metadata                                                                                                       |
| `taskboards.read`, `taskboards.write` | Read or change tasks the person can access                                                                                                                     |
| `calendar.read`, `calendar.write`     | Read or change the person's calendars and events                                                                                                               |
| `files.read`, `files.write`           | Read or change files the person can access                                                                                                                     |
| `mail.read`, `mail.write`             | Read the person's mail; organize threads and send mail that waits for their approval. Used by the [MCP server](/api/mcp)                                       |
| `messages.read`                       | Read conversations the person is in, through the [MCP server](/api/mcp). The REST API reads messages with `workspace.read`                                     |
| `messages.write`                      | Send, edit, pin and react to messages as the person, in conversations they're in                                                                               |
| `tools.read`                          | Discover and run read-only tools across Coline and installed apps                                                                                              |
| `tools.write`                         | Run tools that change things, subject to the person's permissions and app approvals                                                                            |
| `ai.invoke`                           | Call AI endpoints                                                                                                                                              |
| `apps.read`, `apps.write`             | See, or deploy and manage, apps and sites in one workspace. The person picks a workspace they administer on the consent screen, and the token works only there |

## MCP scopes

The [MCP server](/api/mcp) at `/mcp` uses `workspace.read`, `mail.read`, `mail.write`, `messages.read`, `messages.write`, `taskboards.read`, `taskboards.write`, `calendar.read`, `calendar.write`, `files.read` and `files.write`, plus `openid`, `profile` and `email`. Every connection gets all of them, whatever the client asks for, and the consent screen lists what it will be able to do. The full catalog at `/agent` uses `tools.read` and `tools.write`.

## App permissions

Apps built with the [SDK](/sdk) don't use these scopes. They declare permissions in their manifest, such as `files.read` or `network.external`, which a workspace admin approves at install. See the [SDK reference](/sdk/reference#permissions).