Scopes
The permissions an API key or OAuth token can carry.
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 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 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 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 |
messages.read | Read conversations the person is in, through the MCP server. 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 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 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.