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:
Authorization: Bearer vi_…| Detail | |
|---|---|
| Format | Starts with vi_, followed by a long random hex string. |
| Shown | Once, in the API key created dialog. The Key column shows only the first characters afterwards. |
| Stored | As a SHA-256 hash. Nobody, including support, can read a key back. |
| Belongs to | One organisation, and the person who created it. Writes made with the key are recorded under that person. |
| Last used | Updated each time the key authenticates and shown in the Last used column. |
| Rate limit | 120 requests a minute per key |
| Stops working | When 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.
| Scope | Allows |
|---|---|
invitations:write | Create interview invitations. |
invitations:read | Older keys only: read invitations. Treated as candidates:read. |
candidates:read | List candidates and their invitations. |
jobs:read | Read jobs. |
jobs:write | Create and update jobs. |
webhooks:read | List webhook subscriptions. |
webhooks:write | Create and remove webhook subscriptions. |
applications:read | List and read applications with their stage history. |
applications:write | Move applications between stages and import applicants. |
recommendations:read | Read agent recommendations, debrief memos and competency assessments. |
scorecards:read | Read scorecards filed on an interview. |
scorecards:write | File a scorecard as the key’s creator. |
schedules:read | Read interview schedule requests and booked times. |
schedules:write | Ask the scheduling agent to propose slots. |
offers:read | Read offers and their status. |
offers:draft | Create offer drafts. Sending stays with a person in the portal. |
plans:read | Read a job’s goal, stage status and blockers. |
plans:write | Set a job’s headcount, target date, comp band and pause. |
proposals:read | Read open agent proposals. |
proposals:write | Approve or override a proposal. |
decisions:human | Make human-only moves: reject, offer and hire, and approving proposals. Grant it only to a key a person controls. |
assessments:partner | Assessment-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.
| Call | Rule |
|---|---|
moveApplication | Only when the target stage is REJECTED, SCREENED_OUT, OFFERED, ACCEPTED or HIRED. Other stages need only applications:write. |
approveProposal | Always, together with proposals:write. |
overrideProposal | Always, 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.