> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/api/authentication

# 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:

```text
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`](https://parel.si/docs/api/run.md), and `run_tool` and the headline tools over MCP |
| `read` | [`GET /v1/runs/:id`](https://parel.si/docs/api/runs.md), [`POST /v1/quote`](https://parel.si/docs/api/quote.md), [`GET /v1/balance`](https://parel.si/docs/api/balance.md), `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`](https://parel.si/docs/api/discover.md), [`GET /v1/tools`](https://parel.si/docs/api/tools.md) and [`GET /v1/tools/:id`](https://parel.si/docs/api/tool.md) need a valid key but no particular scope. A key without the scope a route needs answers [`insufficient_scope`](https://parel.si/docs/errors.md#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`](https://parel.si/docs/errors.md#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`](https://parel.si/docs/errors.md#unauthenticated) (401). A revoked or mistyped key: [`invalid_key`](https://parel.si/docs/errors.md#invalid_key) (401). After 20 failed attempts in a minute from one IP address, further attempts answer [`rate_limited`](https://parel.si/docs/errors.md#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:

```json
{
  "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:

```json
{
  "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):

```json
{
  "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):

```text
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`](https://parel.si/docs/errors.md#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`](https://parel.si/docs/errors.md#connector_revoked) | 403 | The connector key was revoked in the dashboard. Remove Parel from Claude's connectors and add it again. |
| [`rate_limited`](https://parel.si/docs/errors.md#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` |
