VYG Docs

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.

ShortcutGrants
mcp:toolsEvery non-admin scope an MCP tool uses. Also the default when a client asks for no scope.
mcp:readThe :read scopes from that set.
mcp:writeThe :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.

ScopeAllowsAPI keyNotes
advocacy:adminPOST /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-registrationNoRequires a brand administrator. Sign-in only.
advocacy:readGET /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-statusYes (vyg_ keys)
advocacy:writePOST /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/onboardYes (vyg_ keys)
brand:readget_brandYes (vyg_ keys)
campaigns:readcampaigns, 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}/variantsYes (vyg_ keys)
campaigns:writecampaigns, 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}NoSign-in only.
cdp:readstats, reports, manage_funnel, customers, segments, manage_segment, conversations, cdp_insights_propensity, get_website_breakdownNoAlias for customers:read, insights:read, segments:read, commerce:read. Sign-in only.
commerce:readstats, 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:readGET /v1/contacts, GET /v1/contacts/{id}Yes (vyg_, vyg_ba_ keys)
contacts:read-phoneGET /v1/contacts/{id}/phoneYes (vyg_ keys)
contacts:writesubscribe_signup_form, import_subscribers, POST /v1/list-building/campaigns/{campaign_id}/subscribers, POST /v1/list-building/importsYes (vyg_ keys)
conversations:pauseGET /v1/conversations/{id}/pause, POST /v1/conversations/{id}/pause, POST /v1/conversations/{id}/resumeYes (vyg_ keys)
conversations:readconversations, 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}/traceYes (vyg_, vyg_ba_ keys)
conversations:writePOST /v1/conversations/{id}/messages, POST /v1/conversations/messagesYes (vyg_ keys)
customers:readcustomers, 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}/subscriptionsYes (vyg_ keys)
discounts:writecreate_discount, update_discountNoSign-in only.
events:readdata_sources, GET /v1/event-typesYes (vyg_ keys)
insights:readstats, 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/previewYes (vyg_ keys)
insights:writemanage_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}/duplicateYes (vyg_ keys)
integrations:readdata_sources, klaviyo, email_templates, GET /v1/integrationsYes (vyg_ keys)
integrations:writeklaviyo_import, klaviyo, email_templatesNoSign-in only.
keys:managePOST /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}/rotateNoRequires a brand administrator. Sign-in only.
providers:readdata_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:writemanage_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:readsegments, 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}/historyYes (vyg_ keys)
segments:writemanage_segment, POST /v1/segments, PATCH /v1/segments/{id}, POST /v1/segments/{id}/archive, POST /v1/segments/{id}/duplicateNoSign-in only.
signup_forms:readsignup_forms, GET /v1/list-building/imports, GET /v1/list-building/imports/{id}NoSign-in only.
signup_forms:writemanage_signup_formNoSign-in only.
stats:readstats, GET /v1/statsYes (vyg_ keys)
webhooks:managePOST /v1/webhooks, GET /v1/webhooks, PATCH /v1/webhooks, DELETE /v1/webhooks, POST /v1/webhooks/rotate-secret, POST /v1/webhooks/testYes (vyg_ keys)

On this page