Scopes & Permissions

API keys use granular scopes to control access. Use broad scopes for full access or resource-specific scopes for least-privilege integrations.

Available Scopes

Scope	Description
`read`	Read access to all resources (JDs, resumes, matches, candidates)
`write`	Create and update resources
`admin`	Manage API keys, full access to everything
`jd:read`	Read-only access to job descriptions
`jd:write`	Create and update job descriptions
`resume:read`	Read-only access to resumes
`match:read`	Read-only access to AI match results
`candidate:read`	Read-only access to candidate search

Each endpoint requires at least one of its allowed scopes. For example, GET /jds requires either read or jd:read.

Broad scopes (read, write, admin) include all resource-specific scopes of that level. For example:

Read-only dashboard integration:

{ "scopes": ["read"] }

CI/CD that only pushes JDs:

{ "scopes": ["jd:write"] }

ATS sync that reads matches and creates JDs:

{ "scopes": ["jd:read", "jd:write", "match:read"] }

Admin key for managing other keys:

{ "scopes": ["admin"] }

If your key lacks the required scope:

{
  "success": false,
  "error": "Insufficient scope: requires 'write'"
}

HTTP status: 403 Forbidden