Authentication - intervyo.ai

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

Open Developer settings

Open API Keys

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

Create a key

Click New API key. Name it for the integration that’ll use it (e.g. ats-sync-prod, embed-widget-staging) so audit logs are interpretable.

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.

Pick the smallest scope that works

Scopes are additive. Hand the key only the surface it needs — a key that just creates sessions doesn’t need read access to participants.

Scope	What it allows
`sessions:read`	Read sessions, scorecards, transcripts, recordings.
`sessions:write`	Create + cancel sessions.
`participants:read`	Read participants and resume data.
`participants:write`	Create + update participants.
`templates:read`	Read evaluation templates + stages.
`webhooks:write`	Manage webhook endpoints.

Pick the smallest scope that works

Scopes are additive — grant a key only the surface it needs.

Scope	Grants
`candidates.read` / `.write` / `.delete`	Read / create-update / delete participants
`interviews.read` / `.write`	Read / create sessions and agent profiles
`evaluation_templates.read` / `.write`	Read / manage evaluation templates
`evaluation_stages.read` / `.write`	Read / manage stages
`programs.read` / `.write`	Read / manage programs and enrollments

Copy the secret

The full key is shown once. Copy it to your secret manager immediately. You can rotate it later but you can’t recover the plaintext.

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"

await fetch("https://www.intervyo.ai/api/v1/sessions", {
  headers: { "x-api-key": process.env.INTERVYO_API_KEY! },
});

import os, requests

requests.get(
    "https://www.intervyo.ai/api/v1/sessions",
    headers={"x-api-key": os.environ["INTERVYO_API_KEY"]},
)

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):

Create the replacement key

Generate a new key alongside the old one — they can both be active.

Create the replacement

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

Deploy the new key

Roll the new value through your secret manager. Every running service picks it up.

Deploy the new key

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

Revoke the old key

Once you’ve confirmed traffic has moved over (the audit log on the old key will go quiet), revoke it. Revocation is instant — in-flight requests with the revoked key get 401.

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 [email protected].

​Get an API key

​Authorize a request

​Session (cookie) auth

​Rotating a key

​Rate limits

​Authentication errors

Get an API key

Authorize a request

Session (cookie) auth

Rotating a key

Rate limits

Authentication errors