Skip to main content
VirtualInterview.ai
Docs menu

Authentication and scopes

Every request carries an organisation API key as a Bearer token. A key can do only what its scopes allow, and each operation names the scopes it needs. Moves that reject, offer or hire also need the decisions:human scope, which you should grant only to a key a person operates.

Reference · Last checked against the product on

Bearer API keys

Send the key in the Authorization header of every REST and MCP request:

HTTP header
Authorization: Bearer vi_…
How keys work
Detail
FormatStarts with vi_, followed by a long random hex string.
ShownOnce, in the API key created dialog. The Key column shows only the first characters afterwards.
StoredAs a SHA-256 hash. Nobody, including support, can read a key back.
Belongs toOne organisation, and the person who created it. Writes made with the key are recorded under that person.
Last usedUpdated each time the key authenticates and shown in the Last used column.
Rate limit120 requests a minute per key
Stops workingWhen it is revoked, or when the organisation is suspended or locked for deletion.

Keys cannot be edited. To change a key’s scopes, create a new key, move your integration to it, then revoke the old one. The API Keys card states how many keys an organisation can hold.

Create and revoke keys

Keys are managed under Settings → Developers → API Keys by anyone whose role includes Manage Integrations & API Keys. Click New key, give it a Name, tick its Scopes and click Create key. The step-by-step version is in the API quickstart.

To revoke a key, click the delete icon at the end of its row. The key is removed at once and every request made with it answers 401.

Scopes

Tick only the scopes the integration needs. A request without the right scope answers 403 and names the scope it wanted. The scopes each operation needs are listed in the API reference.

API key scopes
ScopeAllows
invitations:writeCreate interview invitations.
invitations:readOlder keys only: read invitations. Treated as candidates:read.
candidates:readList candidates and their invitations.
jobs:readRead jobs.
jobs:writeCreate and update jobs.
webhooks:readList webhook subscriptions.
webhooks:writeCreate and remove webhook subscriptions.
applications:readList and read applications with their stage history.
applications:writeMove applications between stages and import applicants.
recommendations:readRead agent recommendations, debrief memos and competency assessments.
scorecards:readRead scorecards filed on an interview.
scorecards:writeFile a scorecard as the key’s creator.
schedules:readRead interview schedule requests and booked times.
schedules:writeAsk the scheduling agent to propose slots.
offers:readRead offers and their status.
offers:draftCreate offer drafts. Sending stays with a person in the portal.
plans:readRead a job’s goal, stage status and blockers.
plans:writeSet a job’s headcount, target date, comp band and pause.
proposals:readRead open agent proposals.
proposals:writeApprove or override a proposal.
decisions:humanMake human-only moves: reject, offer and hire, and approving proposals. Grant it only to a key a person controls.
assessments:partnerAssessment-partner endpoints used by applicant tracking system integrations.

invitations:read is kept for keys created before candidates:read existed; the candidates list accepts either.

The decisions:human scope

Some moves decide a candidate’s outcome. The API makes them only for a key that carries decisions:human, and records them under the key’s creator as a person’s decision, never as an agent’s.

What needs decisions:human
CallRule
moveApplicationOnly when the target stage is REJECTED, SCREENED_OUT, OFFERED, ACCEPTED or HIRED. Other stages need only applications:write.
approveProposalAlways, together with proposals:write.
overrideProposalAlways, together with proposals:write.

Without the scope these calls answer 403; a refused stage move carries the code HUMAN_REQUIRED. Offers are never sent through the API at all: offers:draft creates a draft that a person reviews and sends in the portal.

Give decisions:human to a key only when a person triggers each call, for example from an internal review tool. Keep it off any key an AI agent or a scheduled job uses.

Assessment-partner endpoints

Some applicant tracking systems call an assessment provider through their own partner protocol. Those endpoints live under /api/partners/ and accept HTTP Basic authentication, with the API key as the username and an empty password. The key must carry assessments:partner. Paste the key into your applicant tracking system’s assessment settings; you don’t call these endpoints yourself.

Was this page clear?