Scopes
The permission families that gate the REST API and MCP tools.
Scopes follow a family model: <family>:read or <family>:write, where write implies read within the same family. Request the minimum scopes your integration needs — during the OAuth flow (space-separated scope parameter on /oauth-authorize) or when creating an API key in the dashboard.
Scope families
| Field | Type | Description |
|---|---|---|
crm | family | Contacts, companies, deals, pipelines, tasks, bookings, documents, products, calls. Gates the REST contacts/deals/activities endpoints and the CRM MCP tools. |
prospecting | family | Prospect lists and lead analysis. |
social | family | Social accounts, posts, scheduling, inbox, comments. |
ads | family | Ad campaigns, performance, Local Services leads. |
marketing | family | Email/SMS campaigns, funnels, marketing plans, SEO & competitive research. |
content | family | AI copy, image, and media generation. |
web | family | Websites, landing pages, forms, chatbots, quotes. |
support | family | Tickets, CSAT, memberships, referrals, knowledge base. |
insights | family | Reports, web analytics, attribution, audit log. |
workflows | family | Automation workflows and enrollments. |
knowledge | family | Business profile, personas, competitors, goals. |
webhooks | family | Webhook subscriptions (REST Hooks). |
Today the REST API surfaces the crm and webhooks families; the other families gate MCP tools. As REST endpoints expand into those domains they will use the same scope strings.
What each REST endpoint requires
| Field | Type | Description |
|---|---|---|
crm:read | scope | GET /api-deals, GET /api-activities, POST /api-contacts-search. GET /api-contacts and its sub-resources (/:id, /:id/deals, /:id/activities) only require a valid credential — no explicit scope check. |
crm:write | scope | POST /api-contacts, PATCH /api-contacts/:id, DELETE /api-contacts/:id. Implies crm:read. |
webhooks:read | scope | GET /api-webhook-subscriptions and GET /api-webhook-subscriptions/:id. |
webhooks:write | scope | POST /api-webhook-subscriptions and DELETE /api-webhook-subscriptions/:id. Implies webhooks:read. |
On the MCP server, every tool is mapped to one family scope: tools/list shows only tools your credential satisfies, and the scope is re-checked on every tools/call.
Legacy scopes
The original scope strings predate the family model. They keep working — each maps onto its family, so existing Zapier connections and API keys are unaffected:
| Field | Type | Description |
|---|---|---|
contacts:read | legacy | Satisfies crm:read. |
contacts:write | legacy | Satisfies crm:write (and therefore crm:read). |
New integrations should request the family scopes; error messages name the family scope (e.g. crm:write) even when your credential holds the legacy alias.
Example
scope=crm:read%20crm:write%20webhooks:writeA Zapier-style integration that lists contacts, creates contacts, and subscribes to triggers needs crm:read crm:write webhooks:write (write implies read, so webhooks:read comes along automatically).
Scope errors
Calling an endpoint without a satisfying scope returns HTTP 403:
{
"error": "forbidden",
"message": "crm:write scope is required."
}