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 (keys:manage, shopify:admin, klaviyo:admin) are granted only when the person signing in
is a brand admin, and only when asked for by name.
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 |
|---|---|---|---|
brand:read | get_brand | Yes (vyg_ keys) | |
campaigns:read | get_event_journey, list_campaigns, compare_campaigns, get_campaign_composer_options, get_campaign, list_campaign_activity, list_message_variants | Yes (vyg_ keys) | |
campaigns:write | create_campaign, get_campaign_composer_options, rename_campaign, update_campaign_schedule, update_campaign_messages, update_campaign, set_campaign_status, add_message_variant, update_message_variant | No | Sign-in only. |
commerce:read | list_orders, get_order, list_subscriptions, get_subscription, list_products, get_product | Yes (vyg_ keys) | |
contacts:read | GET /v1/contacts, GET /v1/contacts/{id} | Yes (vyg_, vyg_ba_ keys) | |
conversations:read | search_conversations, list_conversations, get_conversation_details, get_conversation_trace, GET /v1/conversations/{id}, GET /v1/conversations/{id}/messages | Yes (vyg_, vyg_ba_ keys) | |
customers:read | list_customer_fields, list_customers, search_customers, get_customer, get_customer_activity, list_customer_orders, list_customer_subscriptions | Yes (vyg_ keys) | |
discounts:write | create_discount, update_discount | No | Sign-in only. |
events:read | list_event_types | Yes (vyg_ keys) | |
insights:read | get_lifetime_value, get_lifetime_value_by_year, get_rfm_tiers, get_top_products, list_at_risk_customers, get_lifecycle_stages, get_customer_overview, get_product_performance, get_first_products, get_acquisition_sources, list_conversation_insights, list_insight_conversations | Yes (vyg_ keys) | |
integrations:read | list_integrations | Yes (vyg_ keys) | |
keys:manage | POST /v1/keys, GET /v1/keys, POST /v1/keys/{id}/rotate, DELETE /v1/keys/{id} | No | Requires a brand administrator. Sign-in only. |
klaviyo:admin | read_klaviyo, write_klaviyo, search_klaviyo_docs | No | Requires a brand administrator. Sign-in only. |
klaviyo:read | read_klaviyo, search_klaviyo_docs | No | Sign-in only. |
providers:read | list_providers, get_provider, list_event_definitions, get_event_definition | Yes (vyg_ba_ keys) | |
providers:write | create_provider, update_provider, create_event_definition, update_event_definition | Yes (vyg_ba_ keys) | |
segments:read | list_customer_segments, list_segments, estimate_segment, get_segment, get_segment_audience, list_segment_members, list_segment_history | Yes (vyg_ keys) | |
segments:write | create_segment, update_segment, archive_segment | No | Sign-in only. |
shopify:admin | read_shopify, mutate_shopify, learn_shopify_api, search_shopify_docs, validate_shopify_graphql | No | Requires a brand administrator. Sign-in only. |
shopify:read | read_shopify, learn_shopify_api, search_shopify_docs, validate_shopify_graphql | No | Sign-in only. |
stats:read | get_performance_stats | Yes (vyg_ keys) |