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:
| Scope | Allows |
|---|---|
run | Paid calls: POST /v1/run, and run_tool and the headline tools over MCP |
read | GET /v1/runs/:id, POST /v1/quote, GET /v1/balance, GET /v1/packs, POST /v1/topup |
admin | Reserved 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-resourceand at the/mcp-suffixed form Claude probes first.resourceis exactly the URL typed into Claude;authorization_serversnames the sign-in server; the only scope isemail. - Every 401 from
/mcpcarriesWWW-Authenticate: Bearer resource_metadata="…", which is what makes Claude start the sign-in. When a token was presented and refused, the header also carrieserroranderror_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 see | HTTP | Meaning |
|---|---|---|
invalid_token | 401 | The 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_team | 403 | The person has no team yet. Create one in the dashboard, then reconnect. |
forbidden | 403 | The person is only a viewer on their teams. A viewer cannot run tools; the owner can make them a member. |
connector_revoked | 403 | The connector key was revoked in the dashboard. Remove Parel from Claude's connectors and add it again. |
rate_limited | 429 | Too 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
| Where | Use |
|---|---|
| claude.ai, Claude Desktop | Sign-in. The connector form has no header field. |
| Claude Code, Cursor, Codex, n8n, any MCP client | An API key in Authorization: Bearer |
| Your own code | An API key in Authorization: Bearer or X-API-Key |
This page as Markdown: /docs/api/authentication.md. Something wrong or missing: hello@parel.si.