Authentication & credentials
The three credentials of a working integration, and how to rotate them.
A working integration uses three distinct credentials. Keeping them in the right place is the single most important security decision.
| Credential | Header | Lives where | May touch |
|---|---|---|---|
Tenant API key (vcp_live_…) | x-api-key | your backend only | create rooms, mint join tokens, read recordings, manage webhooks |
Webhook secret (whsec_…) | — (used to verify) | your backend only | verify the signature on events we send you |
| Participant token (LiveKit JWT) | Authorization: Bearer … | the browser (the only credential your frontend holds) | join one room as one participant |
Never expose the tenant API key to a browser. The key stays on your backend. Your frontend talks to your backend; your backend talks to the platform. A leaked tenant key can create rooms and run up media cost on your account.
Resellers additionally hold a provider key (vcp_prov_…, header
x-provider-key) on their backend only. It provisions and manages tenants; it
never joins meetings. See Provisioning tenants.
Key rotation
Both key types rotate with an overlap window so you never take downtime:
- API key (self-service):
POST /tenant/keys/rotatewith your ownx-api-key(permissiontenant.manage) and{ "gracePeriodSeconds": 86400 }— it rotates the key you called with, carrying over its scope; the old key keeps working for the window while you deploy the new one. Resellers can also rotate any owned tenant's keys viaPOST /provider/tenants/{id}/api-keys/{keyId}/rotate. - Webhook secret:
POST /provider/tenants/{id}/webhook-secret/rotate— during the overlap every delivery is signed with both the new and previous secret (comma-separated inx-webhook-signature), so verification never breaks mid-rotation.
Self-service surface
With just your tenant key you can also:
- Read your own tenant —
GET /tenant(permissiontenant.read): plan, resolved limits, webhook config; never secrets. - Manage webhook delivery —
PATCH /tenant/webhookwith{ "webhookUrl", "webhookEvents" }(permissiontenant.manage).
Test mode
A sandbox tenant (isTestMode: true) issues vcp_test_… keys and lets you
exercise the entire non-media API surface — rooms, tokens, webhooks (including
POST /v1/webhooks/test and the delivery log) — without incurring production
media cost. Billable media (recording, streaming, AI captions) is refused for
a test tenant with TEST_MODE_MEDIA_DISABLED; everything else, including real
rooms and media, behaves exactly like live mode.