Authentication & scopes
Use a revocable customer key with only the permissions your integration needs.
Customer API keys
REST and hosted MCP currently accept a pre-provisioned Recursift API key. Keys have the rsk_live_ prefix, an expiry, revocation state and explicit scopes. Only a hash is stored by the API. Key provisioning and revocation are operator-managed in this release.
Authorization: Bearer YOUR_CUSTOMER_API_KEYNever reuse an endpoint enrollment credential as an integration key. API keys are not human login sessions. /v1/me identifies the calling key and its customer.
Available scopes
| Scope | Permission |
|---|---|
| agents:read | List endpoint metadata |
| query:write | Create and cancel query jobs |
| query:read | Read jobs, answers and stored findings |
| audit:read | Read the customer audit chain |
Scopes are independent. A query:write key receives receipts, not findings. It also needs query:read to retrieve answers. Current grants cover the whole customer; site-restricted keys and human memberships are planned.
Rotation and handling failures
- Store a key per customer integration, server-side. Never make an all-customer shared key.
- Have your operator issue a replacement, update your secret store, verify /v1/me, then revoke the old key.
- 401 means missing, invalid, expired or revoked credentials. 403 means the authenticated request lacks the required scope, or a browser Origin was supplied.
- Do not log Authorization headers, paste live keys into examples, or send credentials to redirected hosts.
OAuth and Authfu: planned
The planned integration binds tokens to the intended resource audience and resolves identity to current customer memberships. It will use the same permission-by-resource policy across the console, API and MCP. No OAuth discovery or token endpoints are advertised in this release.