Scopes

Every operation needs exactly one scope. A scope says what a token may attempt; the platform permissions of the user behind the token decide whether it actually can. Give each token only the scopes its job needs — for an AI assistant they also decide which tools it can see.

How a scope check works

After the token is authenticated and within its rate limit, every call runs these checks in order. The first one that fails ends the request with a 403:

1. Is the area switched on? Administrators can disable a whole resource — every deals:* scope, say — for the organisation in Settings → API Suite. → scope_disabled: “The deals API is disabled for this organisation.”
2. Does the token carry the scope? Scopes match exactly: deals:write does not include deals:read. → missing_scope: “Token lacks the deals:read scope.”
3. Is there a user behind it? Every token acts as someone: you for a personal token, a dedicated service identity for an organisation token. → missing_scope: “The token has no acting user.”
4. Does that user still hold a qualifying permission? Each scope maps to platform permissions (listed below); the user needs any one of them, checked live on every call. → missing_scope: “The token owner does not have permission to use the deals:read scope.”

A scope failure also carries a WWW-Authenticate header naming the missing scope, so OAuth-aware clients — including MCP clients — can ask you to grant it.

Which tokens can hold which scopes

Organisation tokens

An organisation token runs as its own service identity, whose role is given exactly the permissions of the scopes you pick — never super admin. It can hold any scope except these:

They either act on the calling user — their account, notifications, content engagement, approval inbox — or need super admin (investors:admin, internal-users:admin). Creating an organisation token with one of them is refused; use a personal token instead.

Personal tokens and OAuth sign-ins

What you can grant depends on your own access:

• Super admins and API Suite managers can grant any scope.
• Self-service API users can grant the scopes whose permissions they hold themselves, plus the scopes open to any user.
• Data-ingestion operators can grant the two data-ingestion scopes only.

The OAuth consent screen MCP clients use applies the same rules, and leaves out anything you can't grant or that your organisation has switched off.

Common scope sets

All scopes

92 scopes across 47 resources. The user behind the token needs any one of the listed permissions; super admin always qualifies.