Authentication

Two ways in. Claude signs in with your Parel account and the token resolves to a connector key on your team; everything else sends an API key with scopes and caps.

API keys

Keys are created in the dashboard (API keys → Create), shown once, and stored only as a one-way hash. Every key starts with sk_. Send it in one of two headers:

Authorization: Bearer sk_…
X-API-Key: sk_…

Each key has scopes and optional caps, chosen when it is created:

ScopeAllows
runPaid calls: POST /v1/run, and run_tool and the headline tools over MCP
readGET /v1/runs/:id, POST /v1/quote, GET /v1/balance, GET /v1/packs, POST /v1/topup
adminReserved for key and budget management; only a team owner can create a key with it. No /v1 route needs it today.

POST /v1/discover, GET /v1/tools and GET /v1/tools/:id need a valid key but no particular scope. A key without the scope a route needs answers insufficient_scope (HTTP 403), ₹0.

Caps. A key can carry a daily and a monthly spend cap in paise (daily_cap_paise, monthly_cap_paise); the team has its own pair. Caps are checked inside the same transaction that places the hold, with the team row locked, so two calls racing cannot both slip under. A refused call is budget_exceeded (HTTP 429) with cap naming which one: key_daily, key_monthly, team_daily or team_monthly. Days and months are India time.

Failures. No key: unauthenticated (401). A revoked or mistyped key: invalid_key (401). After 20 failed attempts in a minute from one IP address, further attempts answer rate_limited (429) with Retry-After. Use one key per place (a laptop, a server, an n8n workflow) so one can be revoked without touching the others.

Captured on staging, no key:

{
  "ok": false,
  "error": "unauthenticated",
  "message": "Send your API key as `Authorization: Bearer sk_...`.",
  "request_id": "b6f50486-a0ed-4901-b500-51705c619937"
}

A key that does not exist:

{
  "ok": false,
  "error": "invalid_key",
  "message": "This API key is not valid or has been revoked.",
  "request_id": "05b90df2-7c05-4d17-a7b9-b373705cc219"
}

Sign-in from Claude

The MCP endpoint https://api.parel.si/mcp also accepts a user access token from Parel's sign-in server, which is how "Add custom connector" on claude.ai works without a key. The API is an OAuth 2.1 resource server:

  • It publishes protected-resource metadata (RFC 9728) at https://api.parel.si/.well-known/oauth-protected-resource and at the /mcp-suffixed form Claude probes first. resource is exactly the URL typed into Claude; authorization_servers names the sign-in server; the only scope is email.
  • Every 401 from /mcp carries WWW-Authenticate: Bearer resource_metadata="…", which is what makes Claude start the sign-in. When a token was presented and refused, the header also carries error and error_description.
  • Claude registers itself with the sign-in server dynamically ("Register automatically"). The user approves on a Parel page in the dashboard.

The metadata, as https://api.parel.si/.well-known/oauth-protected-resource answers it (captured 2026-11-17; it needs no key):

{
  "resource": "https://api.parel.si/mcp",
  "authorization_servers": [
    "https://lsbpdqkriwunsvtphchp.supabase.co/auth/v1"
  ],
  "scopes_supported": [
    "email"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_name": "Parel"
}

The 401 that starts sign-in, captured from staging (a request to /mcp with no credentials):

HTTP/2 401
WWW-Authenticate: Bearer resource_metadata="https://api.parel.si/.well-known/oauth-protected-resource"

What the token resolves to. A user token never gets its own path through the product. It is verified, then resolved to the user's team (the team they own, else the first team where they are an admin or member; a viewer-only user is refused) and to one hidden key named "Claude connector" on that team, created on first sign-in with the run and read scopes and no caps of its own. From there everything is the key's: scopes, the team's caps, holds, rate limits and the usage log. The connector key is listed under API keys in the dashboard; revoking it disconnects Claude, and the next sign-in creates a fresh one.

You seeHTTPMeaning
invalid_token401The token is invalid, expired, or was not minted for the Parel connector (a dashboard session token does not get in). Sign in again from Claude's connector settings. The WWW-Authenticate header says why.
no_team403The person has no team yet. Create one in the dashboard, then reconnect.
forbidden403The person is only a viewer on their teams. A viewer cannot run tools; the owner can make them a member.
connector_revoked403The connector key was revoked in the dashboard. Remove Parel from Claude's connectors and add it again.
rate_limited429Too many failed sign-in attempts from one IP address in a minute.

API keys are accepted on /mcp exactly as on /v1: a bearer value that starts with sk_ takes the key path; anything else shaped like a token takes the sign-in path.

Which to use

WhereUse
claude.ai, Claude DesktopSign-in. The connector form has no header field.
Claude Code, Cursor, Codex, n8n, any MCP clientAn API key in Authorization: Bearer
Your own codeAn API key in Authorization: Bearer or X-API-Key

This page as Markdown: /docs/api/authentication.md. Something wrong or missing: hello@parel.si.