Authentication
Every request needs an API key, sent as a bearer token.
Every request needs an API key. Create one in the Vidyst studio under Developer → API keys, choose what it may do (its scopes) and copy it: it's shown only once.
Send the key in the Authorization header:
Authorization: Bearer vk_live_…Keys are secrets: keep them on your server and never put them in a web page or mobile app. Browser requests are refused (the API sends no CORS headers). You can restrict a key to your servers' IP addresses, roll it (new secret, old one kept working for a grace period) or revoke it at any time. Call GET /auth/verify to check a key.
What a key looks like
A key is vk_<mode>_<public id>_<secret>. Everything up to the secret is its prefix (vk_live_4fQ9zK2mXp7L): it identifies the key, and it's safe to log and show in your own dashboards. The part after it is the secret, which Vidyst stores only as a hash and can never show you again.
live keys act on real data. test is reserved for a future sandbox.
Scopes
A key is granted scopes per resource, and each endpoint names the one scope it needs (the reference lists it on every endpoint). The API grows endpoint by endpoint: a scope can be granted before every endpoint it covers exists. A :write scope includes :read of the same resource.
| Scope | Allows |
|---|---|
webinars:read | Read webinars and their settings. |
webinars:write | Create and update webinars (includes webinars:read). Deleting will need it too. |
registrants:read | Read registrants and their attendance. |
registrants:write | Register and update registrants (includes registrants:read). |
recordings:read | Read recordings and their download URLs. |
analytics:read | Read webinar and attendance analytics. |
A valid key making a request it has no scope for gets 403 insufficient_scope, with the scope it needs in the required field. Grant it by editing the key in the studio.
Keeping keys safe
- Keep keys in your server's secret store or environment, never in source control, a browser bundle or a mobile app.
- Restrict a key to the IP addresses your servers call from. Requests from anywhere else get
403 ip_not_allowed. - Give each integration its own key with only the scopes it needs, so you can revoke one without touching the others.
- Every key expires. Create a replacement before the date in
expiresAt.
Rolling and revoking
Rolling gives a key a new secret and keeps the old one working for a grace period you choose (up to 7 days), so you can deploy the new secret without downtime. While a request still uses the old secret, usingPreviousSecret in GET /auth/verify is true: use it to confirm the rollout finished.
Revoking stops a key immediately; its requests get 401 revoked_api_key. Revoke a key as soon as you suspect it leaked.
When a key is refused
| Status | Code | Means |
|---|---|---|
401 | missing_api_key | No Authorization header. |
401 | invalid_api_key | Not a key we know, or the secret doesn't match. |
401 | expired_api_key | The key passed its expiresAt. |
401 | revoked_api_key | The key was revoked. |
403 | api_access_disabled | API access isn't enabled for the account. |
403 | ip_not_allowed | The request came from outside the key's IP allowlist. |
403 | insufficient_scope | The key is valid but lacks the scope this endpoint needs. |
A 401 won't become a 200 on retry: fix the key instead. See Errors for the shape of these responses.