Authentication

Every /api/v1 request is authenticated. There are two ways in — and the try-it console in these docs uses the same shared auth control at the top of the page to switch between them.

Two modes, one control

• Session — from a same-origin surface like this docs site, the try-it console calls the API with credentials: "include". If you're signed into a rinkats portal in the same browser, no key is needed. Sign in from the shared auth control (top bar) and you're returned here.
• API key — paste a key once in the shared auth control and every endpoint's Send sends it as Authorization: Bearer …. This is the mode agents and server-to-server callers use.

Bearer API key

Send your key in the Authorization header. An organization member's key (rk_) carries a subset of its owner's roles in one organization; a candidate's key (rkc_) acts as that candidate's profile on the candidate endpoints, with no organization (see API keys).

Key format & environments

Keys are rk_<env>_<body><checksum> — rkc_ for a candidate's key. The environment tag tells prod from test at a glance:

• rk_p_… — production keys.
• rk_s_… — stage / test keys (anything that isn't production, including local dev).
• rkc_p_… / rkc_s_… — a candidate's own keys, the same two environments.

The trailing checksum is an HMAC-SHA256 of the key body, truncated to 8 hex chars, computed with a server-only secret. That makes every key self-validating: a spoofed or mistyped key fails the checksum and is rejected before any database lookup — only the server, holding the secret, can mint a key whose checksum verifies. We persist only a display prefix and a sha256 hash of the full key; the plaintext is shown once and is unrecoverable.

Organizations

Every organization credential is bound to one organization, and data never crosses organizations. An API key takes its org at mint time; an OAuth or session credential acts in the org that was active when it was issued. A user who belongs to several organizations mints one key per organization — there is no way to switch tenants on a request.

Call GET /api/v1/me/organizations (MCP: list_my_organizations) to see every organization the account belongs to, the roles held in each, and which one the current credential is acting in. Ask the user which organization to work in rather than inferring it.

The optional X-Organization header (an org id or slug) is a cross-check, not a selector: when it disagrees with the credential's organization the request is a 404, the same answer any other org's record gets. Send it when you want a mistake to fail loudly instead of writing to the wrong tenant.

Roles decide access

• The path says whose endpoint it is: /api/v1/candidate/…, /api/v1/interviewer/…, /api/v1/recruiter/…, and everything else common to every caller — the same split as the MCP servers (/api/mcp/candidate, /api/mcp/recruiter, /api/mcp/interviewer) and the A2A agents.
• Candidates belong to no organization: a candidate key (rkc_), or OAuth with the candidate scope. It reaches the person's own rinkats space — profile, resume, applications and messages, interviews, matches, applying on the job board — across every role they applied to, and never names an agency. Never salary where the role hides it, never internal stage names. An organization's key is refused there.
• Interviewers reach the interviews they conduct, scorecards, comments and availability under /api/v1/interviewer/….
• Recruiter / lead / admin keys reach the desk under /api/v1/recruiter/… — the requirements and pipelines they're assigned to (admins see all).