Authentication

The contract

Send Authorization: Bearer <token> on every request to a protected endpoint. Tokens are signed JWTs; we verify them on every call. There is no separate query-string or custom-header form.

Service tokens

For backend code, CI, and data pipelines that don't belong to a specific human user, register a service token by POSTing to /v1/register:

curl -X POST https://api.neurynae.com/v1/register \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com" }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "tier": "free",
  "expires_at": "2026-07-29T00:00:00Z"
}

Then include it on every request:

curl -X POST https://api.neurynae.com/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{ "query": "fast TypeScript ORM" }'

User tokens

For per-user calls (the MCP server uses this by default), ToolCairn issues 90-day tokens via the device flow. See the full flow in Device Auth Flow. The credential format is identical to a service token, so the request looks the same:

curl -X POST https://api.neurynae.com/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{ "query": "fast TypeScript ORM" }'

Which should I use?

• Service token — one credential per integration. Best for backend code, CI, scheduled jobs.
• User token (device flow) — one per human. Use when calls must be attributed to an end-user identity (shared usage budgets, audit trails).

Rotation

Tokens are rotated periodically server-side. If you receive a 401 with code token_rotated, mint a new one (service path: re-register; user path: re-run the device flow). The MCP server handles user-token rotation automatically — you only notice if the renewal browser tab fails.

Auth errors

• 401 unauthorized — missing, malformed, or expired token.
• 403 forbidden — token valid but lacks the tier or scope the endpoint requires.
• 429 too_many_requests — rate limit. See Rate limits.