Scopes
Choose permissions for your API key or AI assistant.
Scopes are permissions for actions such as reading customers or editing campaigns. Each
operation lists its accepted scopes; any one is enough. Missing permissions return
403 insufficient_scope.
- API keys carry the scopes chosen when the key was created, from the permissions available for that key. See API keys.
- Sign-in (OAuth) tokens carry the scopes granted at sign-in. See Authentication.
Scope shortcuts for sign-in
A client that signs in can ask for these shortcuts instead of listing scopes one by one. Use individual scope names when requesting only specific permissions.
| Shortcut | Grants |
|---|---|
mcp:tools | Every non-admin scope an MCP tool uses. Also the default when a client asks for no scope. |
mcp:read | The :read scopes from that set. |
mcp:write | The :write scopes from that set. |
Admin scopes (such as keys:manage) are granted only when the person signing in is a brand admin, and only when
asked for by name.
Alias scopes
cdp:read stands for customers:read, insights:read, segments:read and commerce:read: a credential that
carries it is accepted wherever one of those is required. A client may request it by name; the shortcuts above
grant the granular scopes instead.
All scopes
"Allows" names the MCP tools and, for operations without a listed tool, the REST routes. Each tool links to its REST route in the tool catalog.
| Scope | Allows | API key | Notes |
|---|---|---|---|
advocacy:admin | POST /v1/advocacy/memberships/{id}/flag, POST /v1/advocacy/agent-proposals/{id}/decide, POST /v1/advocacy/payouts/{id}/approve, POST /v1/advocacy/payouts/{id}/hold, POST /v1/advocacy/payouts/{id}/release, POST /v1/advocacy/payouts/{id}/cancel, POST /v1/advocacy/a2p-registration | No | Requires a brand administrator. Sign-in only. |
advocacy:read | GET /v1/advocacy/programs, GET /v1/advocacy/programs/{id}, GET /v1/advocacy/advocates, GET /v1/advocacy/advocates/{id}, GET /v1/advocacy/advocates/{id}/profile, GET /v1/advocacy/memberships, GET /v1/advocacy/reward-codes, GET /v1/advocacy/attribution-edges, GET /v1/advocacy/directory, GET /v1/advocacy/campaigns, GET /v1/advocacy/seeding-orders, GET /v1/advocacy/payouts, GET /v1/advocacy/payouts/{id}, GET /v1/advocacy/a2p-registration, GET /v1/advocacy/consent-status | Yes (vyg_ keys) | |
advocacy:write | POST /v1/advocacy/programs, PATCH /v1/advocacy/programs/{id}, POST /v1/advocacy/advocates, POST /v1/advocacy/memberships, POST /v1/advocacy/memberships/{id}/pause, POST /v1/advocacy/memberships/{id}/revoke, POST /v1/advocacy/reward-codes, POST /v1/advocacy/reward-codes/{id}/revoke, POST /v1/advocacy/content, POST /v1/advocacy/content/{id}/rights/request, POST /v1/advocacy/content/{id}/rights/grant, POST /v1/advocacy/content/{id}/rights/revoke, POST /v1/advocacy/campaigns, POST /v1/advocacy/seeding-orders, POST /v1/advocacy/agent-proposals, POST /v1/advocacy/payouts/stripe-connect/onboard | Yes (vyg_ keys) | |
brand:read | get_brand | Yes (vyg_ keys) | |
campaigns:read | campaigns, stats, email_broadcasts, GET /v1/events/journey, GET /v1/campaigns, GET /v1/campaigns/compare, GET /v1/campaigns/composer-options, GET /v1/campaigns/{campaign_id}, GET /v1/campaigns/{campaign_id}/activity, GET /v1/campaigns/{campaign_id}/variants | Yes (vyg_ keys) | |
campaigns:write | campaigns, manage_campaign, manage_email_broadcast, POST /v1/campaigns, GET /v1/campaigns/composer-options, PATCH /v1/campaigns/{campaign_id}, PUT /v1/campaigns/{campaign_id}/schedule, PUT /v1/campaigns/{campaign_id}/messages, PATCH /v1/campaigns/{campaign_id}/flow, POST /v1/campaigns/{campaign_id}/status, POST /v1/campaigns/{campaign_id}/variants, PATCH /v1/campaigns/{campaign_id}/variants/{variant_id} | No | Sign-in only. |
cdp:read | stats, reports, manage_funnel, customers, segments, manage_segment, conversations, cdp_insights_propensity, get_website_breakdown | No | Alias for customers:read, insights:read, segments:read, commerce:read. Sign-in only. |
commerce:read | stats, GET /v1/commerce/orders, GET /v1/commerce/orders/{id}, GET /v1/commerce/subscriptions, GET /v1/commerce/subscriptions/{id}, GET /v1/commerce/products, GET /v1/commerce/products/{id} | Yes (vyg_ keys) | |
contacts:read | GET /v1/contacts, GET /v1/contacts/{id} | Yes (vyg_, vyg_ba_ keys) | |
contacts:read-phone | GET /v1/contacts/{id}/phone | Yes (vyg_ keys) | |
contacts:write | subscribe_signup_form, import_subscribers, POST /v1/list-building/campaigns/{campaign_id}/subscribers, POST /v1/list-building/imports | Yes (vyg_ keys) | |
conversations:pause | GET /v1/conversations/{id}/pause, POST /v1/conversations/{id}/pause, POST /v1/conversations/{id}/resume | Yes (vyg_ keys) | |
conversations:read | conversations, get_checkout_purchase_likelihood, GET /v1/conversations/search, GET /v1/conversations, GET /v1/conversations/{id}, GET /v1/conversations/{id}/messages, GET /v1/conversations/{conversation_id}/trace | Yes (vyg_, vyg_ba_ keys) | |
conversations:write | POST /v1/conversations/{id}/messages, POST /v1/conversations/messages | Yes (vyg_ keys) | |
customers:read | customers, GET /v1/customers/fields, GET /v1/customers, GET /v1/customers/search, GET /v1/customers/propensity-status, POST /v1/customers/propensity-batch, GET /v1/customers/{id}, GET /v1/customers/{id}/timeline, GET /v1/customers/{id}/orders, GET /v1/customers/{id}/subscriptions | Yes (vyg_ keys) | |
discounts:write | create_discount, update_discount | No | Sign-in only. |
events:read | data_sources, GET /v1/event-types | Yes (vyg_ keys) | |
insights:read | stats, reports, manage_funnel, conversations, cdp_insights_propensity, get_website_breakdown, GET /v1/insights/ltv, GET /v1/insights/ltv-by-year, GET /v1/insights/rfm, GET /v1/insights/products, GET /v1/insights/at-risk, GET /v1/insights/lifecycle, GET /v1/insights/overview, GET /v1/insights/product-performance, GET /v1/insights/first-product, GET /v1/insights/sources, GET /v1/insights/cockpit, GET /v1/insights/funnel, GET /v1/insights/funnel/definition, GET /v1/events/samples, GET /v1/insights/acquisition, GET /v1/brand/insights, GET /v1/brand/insights/{insight_id}/conversations, GET /v1/reports, GET /v1/reports/{id}, POST /v1/reports/{id}/run, POST /v1/reports/preview | Yes (vyg_ keys) | |
insights:write | manage_report, manage_funnel, PUT /v1/insights/funnel/definition, DELETE /v1/insights/funnel/definition, POST /v1/insights/funnel/preview, POST /v1/reports, PATCH /v1/reports/{id}, DELETE /v1/reports/{id}, POST /v1/reports/{id}/duplicate | Yes (vyg_ keys) | |
integrations:read | data_sources, klaviyo, email_templates, GET /v1/integrations | Yes (vyg_ keys) | |
integrations:write | klaviyo_import, klaviyo, email_templates | No | Sign-in only. |
keys:manage | POST /v1/keys, GET /v1/keys, GET /v1/key-scopes, GET /v1/keys/{id}, PATCH /v1/keys/{id}, DELETE /v1/keys/{id}, POST /v1/keys/{id}/rotate | No | Requires a brand administrator. Sign-in only. |
providers:read | data_sources, GET /v1/providers, GET /v1/providers/{provider_id}, GET /v1/providers/{provider_id}/event-definitions, GET /v1/providers/{provider_id}/event-definitions/{definition_id} | Yes (vyg_, vyg_ba_ keys) | |
providers:write | manage_data_source, POST /v1/providers, PATCH /v1/providers/{provider_id}, POST /v1/providers/{provider_id}/event-definitions, PATCH /v1/providers/{provider_id}/event-definitions/{definition_id} | Yes (vyg_, vyg_ba_ keys) | |
segments:read | segments, manage_segment, GET /v1/customers/{id}/segments, POST /v1/customers/segments-batch, GET /v1/events/catalog, GET /v1/events/campaigns, GET /v1/segments/summaries, POST /v1/segments/estimate/batch, GET /v1/segments/goal-defaults, GET /v1/segments, POST /v1/segments/estimate, POST /v1/segments/count, POST /v1/segments/value, GET /v1/segments/{id}, GET /v1/segments/{id}/audience, GET /v1/segments/{id}/members, GET /v1/segments/{id}/history | Yes (vyg_ keys) | |
segments:write | manage_segment, POST /v1/segments, PATCH /v1/segments/{id}, POST /v1/segments/{id}/archive, POST /v1/segments/{id}/duplicate | No | Sign-in only. |
signup_forms:read | signup_forms, GET /v1/list-building/imports, GET /v1/list-building/imports/{id} | No | Sign-in only. |
signup_forms:write | manage_signup_form | No | Sign-in only. |
stats:read | stats, GET /v1/stats | Yes (vyg_ keys) | |
webhooks:manage | POST /v1/webhooks, GET /v1/webhooks, PATCH /v1/webhooks, DELETE /v1/webhooks, POST /v1/webhooks/rotate-secret, POST /v1/webhooks/test | Yes (vyg_ keys) |