docs get started
Authentication
API keys, OAuth for MCP clients, scopes, and key rotation.
Every route needs a bearer token except workspace signup, email verification, public plans, and the opt-out flow.
Authorization: Bearer rmcp_live_…
POST /v1/workspaces needs a name and an email. It returns the key once, with every scope, and a balance of 0. We email a confirmation link. Confirming it (POST /v1/workspaces/verify with the token, or the button on the link's page) adds 1,250 credits. The link works once and expires after 48 hours. Free credits are granted once per email address, and a +tag counts as the same address. Signups are limited per network, and there is a daily limit on free grants across the platform. When that limit is reached, the verify call returns 429 and the same link works the next day.
Keys created before rmcp_live_ existed (rapi_live_…) keep working.
Scopes
| Scope | Allows |
|---|---|
sourcing:read | Read searches, people already fetched, the seen register, lists, and free lookups |
sourcing:spend | Run searches, fetch and match people, write the seen register and lists. Spends credits |
contacts:spend | Look up personal email and phone for fetched people. Spends credits |
outreach:read | Read outreach accounts, sequences, enrollments, actions, and conversations |
outreach:write | Connect accounts, edit sequences, settings, and caps. Sends nothing |
outreach:send | Enroll candidates, send single actions, reply, resume, and approve messages |
privacy:write | Erase people, manage suppressions, delete caches and contact data |
account:read | Read the workspace, balance, usage, events, keys, customers, and webhook endpoints |
account:manage | Create and revoke keys, customers, and webhook endpoints |
billing:manage | Start checkouts and change the subscription plan |
A missing scope is 403 insufficient_scope with details.required_scope. MCP tools check the same scopes. A preview, ?dry_run=true on REST or a tool call without confirm, only needs the matching read scope: sourcing:read for sourcing and contacts, outreach:read for outreach. A key can only grant scopes it holds, and a key created by a capped key cannot have a higher daily_cap_credits.
Keys can be bound to a customer (customer_id), carry a daily credit cap, expire (expires_at), and pin an API version.
OAuth for MCP clients
The MCP server is an OAuth 2.1 protected resource. Clients such as claude.ai discover it from /.well-known/oauth-protected-resource, register themselves (POST /oauth/register), and send the recruiter to a consent page. The recruiter pastes an API key once, picks permissions (sending outreach is a separate box), and optionally a customer and a daily cap. The client gets a one-hour access token (rmcp_oat_…) and a rotating refresh token. Spending and account management scopes beyond what the key holds are never granted, and account:manage and billing:manage are not available over OAuth. Revoking the API key that approved the grant ends it.
Rotate a key
Create a read-only key, then delete it. The script uses the workspace key to do both.
#!/usr/bin/env bash
set -euo pipefail
DOMAIN="${RECRUITMCP_DOMAIN:-recruitmcp.com}"
BASE="${RECRUITMCP_BASE:-https://api.${DOMAIN}}"
MCP="${RECRUITMCP_MCP:-https://mcp.${DOMAIN}/mcp}"
WS=$(curl -fsS -X POST "$BASE/v1/workspaces" -H 'content-type: application/json' -d '{"name":"Northwind Search","email":"ada@northwind.example"}')
KEY=$(node -e 'process.stdout.write(JSON.parse(process.argv[1]).api_key)' "$WS")
CREATED=$(curl -fsS -X POST "$BASE/v1/api-keys" -H "authorization: Bearer $KEY" -H 'content-type: application/json' -d '{"name":"read only","scopes":["sourcing:read"]}')
KID=$(node -e 'const j=JSON.parse(process.argv[1]); if(!j.api_key||!j.scopes?.includes("sourcing:read")||j.scopes.includes("sourcing:spend")) process.exit(1); process.stdout.write(j.id)' "$CREATED")
curl -fsS -X DELETE "$BASE/v1/api-keys/$KID" -H "authorization: Bearer $KEY" -o /dev/null
DELETE /v1/api-keys/{key_id} returns 204. The deleted key stops working at once.
What it costs
Issuing and revoking keys is free.
Reference: createWorkspace, listApiKeys, createApiKey, revokeApiKey in the API reference.