VYG Docs

API keys

Create and manage API keys for your server integrations.

A VYG API key lets a server call REST routes at https://api.vyg.app/v1 or MCP tools at https://api.vyg.app/mcp. The key belongs to one brand and carries only the scopes chosen when it was created.

Create a key

A brand admin opens Settings → API keys (/settings/api-keys) and selects Create API key:

  1. Name the key after the app or teammate that uses it, for example "Marketing hub".
  2. Choose Access. Read-only reads campaigns, stats, segments, conversations, contacts and the other resources the brand has. Read & write adds every write an API key may hold, such as contacts. Custom sets None, Read or Write per resource; write always includes read.
  3. Choose when the key expires: 30 days, 90 days (the default), 1 year, or never.

The new key starts with vyg_ and is shown once, with ready-to-paste examples for curl, JavaScript and MCP clients such as Claude and Cursor. Creating another key leaves existing keys active.

Each resource maps to these scopes:

ResourceReadWrite
Brand profilebrand:read
Campaignscampaigns:readcoming soon
Stats & reportsstats:read
Conversationsconversations:read
Contactscontacts:readcontacts:write
Insightsinsights:readinsights:write
Segmentssegments:readcoming soon
Customerscustomers:read
Events & commerceevents:read, commerce:read
Data sourcesintegrations:read
Advocacyadvocacy:readadvocacy:write
Custom providersproviders:readproviders:write

Segments, Customers, Events & commerce and Data sources appear only for brands with customer data features. Sending or activating campaigns, discounts, Shopify, Klaviyo and key management stay sign-in only.

Send the key as a bearer token in the Authorization header. Keep it on your server, never in browser or mobile app code.

Authorization: Bearer vyg_…

Manage a key

Select a key in the list to see its access, its requests per day for the last week, when and from where it was last used (REST or MCP), and its history of changes.

  • Rename and Edit access change the key in place. The key value stays the same, so anything using it picks up the new access on its next request.
  • Roll key creates a new key with the same name, access and expiry. Choose how long the current key keeps working: now, 1 hour, 24 hours or 7 days. Use Now if the key leaked.
  • Revoke stops the key immediately. A key used in the last 7 days asks you to type its name first.

Keys unused for 90 days are marked Unused, and keys ending within 14 days are marked.

Manage keys over the API

The /v1/keys routes require an OAuth sign-in token with keys:manage, available to brand admins. An API key cannot create, rotate or revoke keys, or change them.

MethodPathAction
POST/v1/keysCreate a key with scopes, and optionally name and expires_at; plaintext is returned once
GET/v1/keysList keys without plaintext
GET/v1/key-scopesThe scopes this brand can give a key right now
GET/v1/keys/{id}One key with usage (requests per day, last 30 days) and history
PATCH/v1/keys/{id}Change name, scopes or expires_at; the key value does not change
POST/v1/keys/{id}/rotateReplace a key; grace_seconds (up to 604800) keeps the old key working for that long
DELETE/v1/keys/{id}Revoke one key by id

For a vyg_ key, use key_class=cdp: as a query parameter on GET and DELETE, and as a body field on POST and PATCH. Use the key id, not its display prefix.

GET /v1/keys returns { "data": [...], "next_cursor": null } with every key in one page. The other routes return the key record itself:

{
	"id": "5b0f6c2a-3e1d-4f8a-9c7b-1a2d3e4f5a6b",
	"key_prefix": "vyg_3f9c",
	"brand_id": "b7a1c2d3-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
	"scopes": ["campaigns:read", "stats:read"],
	"name": "Marketing hub",
	"created_by": "admin@example.com",
	"created_at": "2026-10-26T10:00:00.000Z",
	"last_used_at": null,
	"last_used_ip": null,
	"last_used_via": null,
	"requests_7d": 0,
	"expires_at": "2027-01-24T10:00:00.000Z",
	"revoked_at": null,
	"plaintext": "vyg_…"
}

plaintext is only on the record that create and rotate return, and only that once.

Legacy vyg_ba_ keys

Keys starting with vyg_ba_ were issued for custom providers before keys worked across the whole API. They appear in Settings → API keys with a Legacy badge and keep working until revoked, but they only reach custom provider operations. Create a new key with Custom providers access to replace one. Use key_class=brand-api to list or revoke them over the API.

Keep keys safe

Store each key in a server-side secret store. Give each integration its own key and only the scopes it uses, so you can revoke one integration without interrupting the others. If a plaintext key is lost, revoke it and create a replacement.

On this page