Create an API key and choose the permissions your integration needs.
Authentication and scopes
Authenticate REST API requests with an API key from your Litmus organization.
Send it in the Authorization header using the Bearer scheme.
API keys
- Sign in to the Litmus dashboard as an organization admin and select the organization your integration will use.
- Open Settings → API Keys → Create key.
- Enter a name that identifies the integration, such as
Interview scheduling. - Select the scopes it needs from the table below. At least one scope is required.
- Create the key and copy it. The full key is displayed only once.
Store the key in your backend's secret manager or environment configuration. Keep it out of browser code, source control, and request logs. Keys remain valid until revoked in Settings → API Keys.
Choose scopes for your workflow
| Workflow | Scopes |
|---|---|
| Find roles and inspect their rounds | roles:read |
| Send take-home invites or ask candidates to choose a live interview time | roles:read, invites:write |
| Book and manage live interviews | roles:read, interviews:read, interviews:write |
| Monitor interviews for a known posting | interviews:read |
| Read assessment results | submissions:read |
For the scheduling quickstart, select roles:read,
interviews:read, and interviews:write. Add invites:write only if your
integration also sends invitations for candidates to schedule themselves.
If you already have a posting_id, you can omit roles:read from a scheduling
integration: interviews:read also authorizes reading that posting's pipeline.
Read and write scopes are independent. interviews:write does not grant
interviews:read.
Send a request
Set LITMUS_API_KEY to your key in your backend environment. Examples use this
variable instead of including a key in each request.
curl --fail-with-body https://litmushiring.com/api/v1/roles \
-H "Authorization: Bearer $LITMUS_API_KEY"This request requires roles:read and returns 200 with a roles array. An
empty array means the request succeeded but the organization has no postings
to return.
Each key belongs to one organization. You do not send an organization ID in
REST requests. Resources outside that organization return 404.
Scopes
One API key can authenticate both the REST API and the MCP server. The same scope selections apply to both. A scope grants access only to the operations exposed by each interface; some capabilities are available through MCP only.
| Scope | REST API access | Additional MCP access |
|---|---|---|
roles:read | List roles and read pipeline rounds. | Read roles and pipeline status. |
candidates:read | No dedicated REST endpoint. | Read candidates and their pipeline stages. |
invites:write | Send assessment invitations. | Invite candidates. |
assessments:read | No dedicated REST endpoint. | Read assessment files and context. |
assessments:write | No dedicated REST endpoint. | Create assessments and edit their files. |
graders:read | No dedicated REST endpoint. | Read an assessment's Grader Prompt and grader attachments. |
graders:write | No dedicated REST endpoint. | Save a Grader Prompt and upload grader attachments. |
submissions:read | Read a submission and its result. | Read reports, evidence, and session activity. |
submissions:write | No dedicated REST endpoint. | Record advance, reject, or pending decisions on submissions. |
interviews:read | Read interviews, pipeline rounds, interviewers assigned to a role, and available slots. | See the MCP tool reference for supported operations. |
interviews:write | Book, reassign, and cancel interviews; update interviewers and their availability. Booking an email that isn't a candidate yet adds them; a scheduled booking emails them the assessment link, an externally scheduled one returns it for you to send. | See the MCP tool reference for supported operations. |
sandboxes:write | No dedicated REST endpoint. | Open a live sandbox on a submission and run its code. |
archives:read | No dedicated REST endpoint. | Download a submission's code as a zip (get_submission's zipUrl). Leave it off to keep candidate code off your machines; reading it and running it in a sandbox still work. |
Change a key's scopes
Use the edit action on a key's row in Settings → API Keys to change its scopes. Changes apply to the next request without replacing the key. Revoking a key prevents subsequent requests from authenticating.
Full access selects every currently available scope. Scopes added later must be granted explicitly. Legacy keys created before scopes were introduced retain unrestricted access until their permissions are edited.
Missing a scope
| Status | Meaning | Action |
|---|---|---|
401 | Missing or invalid Bearer credentials, a revoked key, or an organization that is not approved for access. | Check the header and key, and confirm your organization is approved. Use a key created in API Keys, not an ATS partner credential. |
403 | The key is valid but lacks a required scope. | Add the scope named in the response. |
404 | The requested resource does not exist in the key's organization. | Check the resource ID and the organization that issued the key. |
Litmus API keys are separate from credentials used to connect an applicant tracking system. You do not need an ATS connection to call the REST API.
Audit log
Open Settings → Audit Log to inspect authenticated REST requests and MCP tool calls. Entries identify the key, endpoint, status, duration, and relevant resource IDs. Request bodies are not recorded. Filter by key to inspect one integration's activity. Requests that fail authentication are not attributed to a key.