OAuth scopes
The 62 scopes Whippy's authorization server offers, and how they combine with your role.
Scopes limit what an OAuth token can do. They work together with your Whippy role:
- A tool call succeeds only if your role allows the action and, for scope-protected endpoints, the token has the matching scope.
- A scope never gives you more access than your role. A user without permission to delete contacts can't delete them through MCP, even with
contacts:delete.
Scopes use the format resource:permission, the same resources and permissions as Whippy roles.
Which scopes your client gets
MCP clients read the scope list from https://api.whippy.co/.well-known/oauth-authorization-server and usually request all of them. Claude, ChatGPT, and Cursor all do this.
If a client requests no scopes, the token has none. Read and write calls on unprotected endpoints (such as conversations and messages) still work, but every scope-protected tool fails with:
{"error": "Token does not have the required scope for this action."}If you see this error, check that your client requests scopes, then disconnect it from Connected apps and sign in again.
Endpoints without a scope
Some endpoints aren't scope-protected. Your role alone decides access. These include conversations, messages, calls, reading channels, users, organization details, and contact lists.
list_organization_variables always returns built-in variables. It includes custom object and form variables only when the token also has custom_data_types:read or forms:read.
Scope list
| Resource | Scopes |
|---|---|
| Contacts (also leads and segments) | contacts:read, contacts:create, contacts:update, contacts:delete |
| Campaigns | campaigns:create, campaigns:update |
| Sequences | sequences:read |
| AI Agents (also knowledge bases, LLMs, agent tools, and tests) | ai_agents:read, ai_agents:create, ai_agents:update, ai_agents:delete |
| Automation templates | automation_templates:read |
| Tags | tags:create, tags:update, tags:delete |
| Custom object definitions | custom_data_types:read, custom_data_types:create, custom_data_types:update, custom_data_types:delete |
| Custom object properties | properties:create, properties:update, properties:delete |
| Custom object records | custom_data:read, custom_data:create, custom_data:update, custom_data:delete |
| Developer applications | applications:read, applications:create, applications:update |
| Webhook endpoints | endpoints:read, endpoints:create, endpoints:update |
| Metrics | metrics:read, metrics:create, metrics:update, metrics:delete |
| Reports and dashboards | custom_reports:read, custom_reports:create, custom_reports:update, custom_reports:delete |
| Teams (also team members and schedules) | teams:read, teams:create, teams:update, teams:delete |
| Message templates | message_templates:create, message_templates:update, message_templates:delete |
| Invites | invites:create, invites:delete |
| Workflows | workflows:read, workflows:create, workflows:update |
| Skills | agent_skills:read, agent_skills:create, agent_skills:update, agent_skills:delete |
| Forms | forms:read, forms:create, forms:update, forms:delete |
| Audit logs | audit_logs:read |
| Channels | channels:update |
Known gap
delete_developer_applicationanddelete_developer_endpointrequireapplications:deleteandendpoints:delete, which the authorization server doesn't offer yet. Over OAuth these two tools always return the insufficient-scope error. Delete applications and webhook endpoints in the Whippy app, or with an API key.
Updated about 3 hours ago