API keys

Keys are self-serve and belong to the person who creates them — no admin approval, no elevated scopes. There are two kinds: an organization member's key and a candidate's own key.

Where

• Organization members (recruiter, lead, admin, billing, interviewer) manage rk_ keys on /account → Organisation API keys (reachable from the user chip in any portal's top bar). They reach /api/v1/recruiter/…, /api/v1/interviewer/… and the common endpoints, and the /api/mcp/recruiter and /api/mcp/interviewer servers.
• Candidates manage rkc_ keys in their account settings, /account → Candidate API keys. A candidate belongs to no organization, so the key belongs to the profile it was created on and to nothing else. It reaches /api/v1/candidate/…, /api/mcp/candidate and /api/a2a/candidate only — every organization endpoint refuses it with 403, and the candidate endpoints refuse an organization's key the same way. A profile holds at most ten live keys, and keys are created and revoked signed in: a key never mints another.

How they work

• Keys look like rk_p_… (an organization member's) or rkc_p_… (a candidate's). The full value is shown once at creation — copy it then.
• We store only a display prefix and a sha256 hash. We can never show you the full key again.
• Lists show each key's name, prefix, scope, created date and last-used time.
• Revoke instantly — a revoked key is rejected with 401 on the next call.

One key, one organization (organization members)

• A key is bound to the organization you were acting in when you created it, and it can only ever read and write that organization's data.
• Belong to several organizations? Switch organization first, then create a key there — one key per organization. There is no header or parameter that switches tenants mid-request.
• Ask GET /api/v1/me/organizations which organization a key is acting in, and what else the account can reach.
• Sending X-Organization (id or slug) cross-checks the key: a mismatch returns 404, so a misrouted script fails instead of writing to the wrong place.

Role scope (least privilege)

• When you create a key, you pick which of your own roles it acts as — a subset, never more.
• Effective roles on a request are your live roles ∩ the key's scope. A key scoped to interviewer gets 403 on the recruiter endpoints even if you are also a recruiter. An organization's key never carries the candidate role: a candidate's key is their own, above.
• Scope can only ever narrow access. Lose a role and any key scoped to it stops reaching those endpoints.
• Signing in with your session (the docs try-it console) always carries your full roles — scoping applies to keys only.