Skip to main content
Every API request authenticates with a workspace-scoped API key sent in the x-api-key header. Keys are created in the team dashboard and are prefixed iv_live_.

​
Get an API key

1

Open API Keys

In the team dashboard, go to Developer → API Keys.
2

Create a key

Click New API key. Name it for the integration that will use it (e.g. ats-sync-prod, embed-widget-staging) so audit logs stay readable.
3

Pick the smallest scope that works

Scopes are additive — grant a key only the surface it needs.
ScopeGrants
candidates.read / .write / .deleteRead / create-update / delete participants
interviews.read / .writeRead / create sessions and agent profiles
evaluation_templates.read / .writeRead / manage evaluation templates
evaluation_stages.read / .writeRead / manage stages
programs.read / .writeRead / manage programs and enrollments
4

Copy the secret

The full key (iv_live_…) is shown once. Copy it into your secret manager immediately — you can rotate it later, but you can’t recover the plaintext.

​
Authorize a request

Send the key in the x-api-key header: 
curl "https://www.intervyo.ai/api/v1/sessions" \
  -H "x-api-key: iv_live_your_key_here"
Never ship API keys to a browser, mobile bundle, or any client surface — a key grants workspace-wide access on its scopes. Call the API from your own backend, or use the embed widget, which exchanges short-lived participant tokens instead.
Requests made from a signed-in dashboard session can authenticate with cookies instead of a key. For those calls, pass your team slug as the accountSlug query parameter so the API can resolve the workspace: 
curl "https://www.intervyo.ai/api/v1/participants?accountSlug=<your-team-slug>"
Most server-to-server integrations should use an API key, not cookie auth.

​
Rotating a key

API keys don’t auto-expire. Rotate them on your org’s secrets schedule (90 days is common):
1

Create the replacement

Generate a new key alongside the old one — both can be active at once.
2

Deploy the new key

Roll the new value through your secret manager so every service picks it up.
3

Revoke the old key

Once traffic has moved over (the old key’s audit log goes quiet), revoke it. Revocation is instant — in-flight requests with the revoked key get 401.

​
Rate limits

Limits scale with your plan. Every response includes rate-limit headers: 
X-RateLimit-Limit:      120
X-RateLimit-Remaining:  118
X-RateLimit-Reset:      1735689600
A 429 Too Many Requests includes a Retry-After header (seconds). Back off and retry, or batch your work to lower request frequency.

​
Authentication errors

​
401 Unauthorized
Missing, malformed, or revoked API key. Check the x-api-key header and verify the key under Developer → API Keys.
​
402 Payment Required
The workspace has no active paid plan (or is out of credits). The candidate-facing apply flow keeps working on trial; programmatic session creation requires a paid plan.
​
403 Forbidden
The key is valid but lacks the scope this endpoint requires. Add the missing scope, or use a different key.
Need OAuth, SSO-scoped tokens, or service accounts? Contact enterprise@intervyo.ai.
Last modified on June 2, 2026