Scopes

This page is generated from src/services/scope-catalog.ts — the catalogue the backend checks on every call — and from the route table that spends those permissions. It cannot name a scope that does not exist, and the "What it opens" column is recounted on every build: it is the number of operations that require the scope today, not a figure somebody typed.

The chapter that explains how a credential is minted, read and revoked is Authentication and API keys.

What a scope is

A permission shaped resource:action. What sits before the colon is the resource; what sits after it is what you may do with it. A credential carries its own in a list and holds nothing beyond them.

• An operation may accept several scopes, and one is enough. The middleware guarding it takes several and reads them as an OR: carry any one of them and you are through. That is why the same operation is counted in more than one row.
• Nobody hands out what they do not hold. When a credential is minted, the platform rejects any scope the minter does not carry. An API key never comes out wider than the person or credential that created it.
• * exists and it is not for you. It is the wildcard on the platform bootstrap credentials. No role carries it, and the mint form will not take it.
• A scope is not the whole gate. It says which family of operations you may call, not which records you may see: record visibility — and, where it applies, published-inventory visibility — still sits on top. A scope opens the route; it does not decide what comes back.
• A scope with no route is not a dead scope. A few of them guard a field inside another response, a tool on the MCP server or a background job, and one or two are reserved for an operation that does not exist yet. The table says so rather than hiding them.

How to read a row

• Scope — the exact string that goes in scopes when the credential is minted. The table is sorted by that string, so the scopes of one resource sit together.
• What it opens — how many API operations require it today, followed by the areas of the contract they reach. When the area is one of the chapters this site publishes, it is linked; otherwise the tag is named as the contract spells it. The tier of those operations closes the cell: estable changes only through deprecation, beta may change with a changelog entry, interna is not part of the public API and may change without notice.
• Roles — which of the four built-in roles carry it. A custom role is built from any admin scope, never from an owner one.
• Marks — owner only when no admin carries it; sensitive when one of its operations touches personal or health data beyond ordinary contact fields; connector preset when the guided connect flow for a Connected app includes it; pk_ when a browser-side publishable key carries it.

Every scope

182 scopes: the ones the built-in roles hand out, plus the connector preset and the publishable-key set. Deprecated spellings are at the foot of the page.

The connector preset

What the guided connect flow for a Connected app mints: one read permission per tool family the connector profile exposes, and nothing else. It is not a role, and no person carries it.

mcp:connector sits inside it, and it is not a permission: it guards no route, no tool, no field and no column. Its only effect is to take capability away from its bearer — the MCP server sees the marker and narrows its catalogue to a read-only profile — which is why it can travel in plain sight on the credential: there is nothing to escalate to. A credential carrying this marker and nothing else can do strictly less than a credential carrying nothing at all.

• analytics:read
• appointment_types:read
• appointments:read
• clinic:read
• contacts:read
• conversations:read
• followups:read
• help_centers:read
• leads:read
• marketplace:read
• mcp:connector
• pipelines:read
• price_approval:read
• teams:read
• tenant:read
• tickets:read
• vehicle_pipeline:read

Margin and cost reading is not included: it is added by ticking the matching box while connecting, and without that scope those tools are absent from the catalogue rather than present and refusing.

Publishable pk_ keys

A pk_ key lives in the browser, so it carries no scopes of its own: the platform resolves this fixed set for it on every request. No role hands it out and the mint form does not offer it; a pk_ can never carry a broad write or an admin permission.

• appointments:intake
• leads:intake
• stock:read
• storefront_events:write
• widget:chat

Adding an entry to this set grants it to every pk_ already in the wild, with no re-mint — which is why the list stays short and every entry opens exactly one public surface.

Deprecated spellings

A one-release bridge: a credential carrying the old string is treated as carrying the new one, and nothing else changes. The deprecated spelling cannot be handed out, no role offers it and the mint form will not take it — it only keeps working on the credentials that already had it.