Authentication

The REST API uses two layers of authentication:

API Key

Used for administrative operations (discovering layouts, creating tokens). Pass it as a header:

x-api-key: <keyId>.<secret>

API keys are per-team and scoped — a key belongs to one team and may only mint tokens (or read info) for the layouts in its scope (the team’s own layouts by default, or an explicit allow-list). A Volta admin issues a key from the team management page; the secret is shown once at creation, so store it securely. A key can be revoked at any time, is independently identifiable, and only ever mints audience-level tokens.

Rotating a key

Keys don’t expire, so rotate them on a schedule or after any suspected exposure. Rotation is a create-then-revoke sequence — there’s no automatic grace window, so cut over before revoking:

Issue a new key for the team (same scope) from the team management page and copy its secret.
Update your integration to send the new key, and deploy it.
Once you’ve confirmed live traffic is using the new key, revoke the old one.

Revocation takes effect immediately — revoking the old key before the new one is live will fail in-flight requests.

Bearer Token (JWT)

Used for sending audience actions. Obtained from the POST /token endpoint:

curl -X POST https://YOUR_API_URL/token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"layoutId": "YOUR_LAYOUT_ID"}'

Pass the returned token in subsequent action requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token properties

Algorithm: HS256
Signed with: AUDIENCE_CLIENT_SECRET (internal)
Permissions: Audience-level (no admin access)
Expiry: Tokens are lightweight and long-lived, but it’s good practice to refresh them periodically or on reconnect

Recommended flow

For production apps:

Your backend calls POST /token with the API key
Your backend returns the JWT to your client app
The client app uses the JWT directly for POST /action

This keeps the API key out of client code.