# auth.md

Authentication instructions for agents accessing the Drel API.

Drel's public REST API (`/api/public/v1/*`) and MCP server (`/api/mcp`) accept two
credential types. Use whichever fits how your agent runs:

| | API key | OAuth |
| --- | --- | --- |
| Best for | Unattended / machine use | A human authorizing a specific agent |
| Setup | Generate once in Settings | Standard OAuth 2.0 authorization |
| Scope | Unscoped (full read access) | `cases:read` (currently the only scope) |
| Who issues it | Drel | Clerk (Drel's identity provider) |

## Option 1 — API key (unattended use)

1. Sign in to your Drel workspace at [app.drel.ai](https://app.drel.ai).
2. Go to **Settings → MCP** ([app.drel.ai/settings/mcp](https://app.drel.ai/settings/mcp)).
3. Generate a key. It is shown once, in the form `drel_pk_...` — store it securely.

A human has to do this step. There is no unattended/self-service registration flow for
an agent to complete on its own.

Send it as a standard bearer token on every request:

```
Authorization: Bearer drel_pk_...
```

The same key authenticates both the REST API and the MCP server. It is scoped to the
workspace of the user who generated it — every response is limited to that workspace's
own AI Security Review cases, never another org's data. Rotating or revoking a key from
Settings → MCP immediately invalidates it; there is no refresh-token flow to keep alive
separately.

## Option 2 — OAuth 2.0 (user-delegated use)

For an agent that wants a human to explicitly authorize it (rather than being handed a
long-lived key directly), Drel supports standard OAuth 2.0 Authorization Code + PKCE.
**Clerk is the Authorization Server; Drel is the Resource Server.** Drel does not run its
own authorization endpoint, token endpoint, or JWKS — those all belong to Clerk.

Discovery is fully machine-readable, per spec:

- [/.well-known/oauth-protected-resource](https://drel.ai/.well-known/oauth-protected-resource)
  (RFC 9728) — tells your client where the Authorization Server is and what scope to
  request.
- [/.well-known/oauth-authorization-server](https://drel.ai/.well-known/oauth-authorization-server)
  (RFC 8414) — Clerk's real authorization/token/JWKS endpoints, proxied live so this
  document is never stale.

The only scope today is `cases:read` — it covers every read operation the API and MCP
server currently expose. There are no write scopes, because there is nothing to write to
yet.

**Not for unattended/machine use.** Clerk does not yet support the OAuth
client-credentials grant, so there is no way to obtain an OAuth token without a human
completing an authorization step. Use an API key (Option 1) for anything that runs
without a person present.

A token that authenticates but lacks `cases:read` gets `403` with
`WWW-Authenticate: Bearer error="insufficient_scope"` — re-request authorization with
the scope, don't retry the same token.

## Errors

Both credential types share the same error shape (`application/problem+json`, RFC 9457):
missing/invalid/expired credential → `401` (with `WWW-Authenticate` pointing at the
protected-resource metadata above); valid credential, wrong scope → `403`. Every
response — including these two — carries `RateLimit-Limit`/`RateLimit-Remaining`/
`RateLimit-Reset` headers (60 requests/minute per credential on the REST API and MCP
`resources/*` methods; 30/minute per IP on the unauthenticated MCP
`initialize`/`ping`). Full error-code reference:
[/developers#errors](https://drel.ai/developers#errors).

## Reference

- [/openapi.json](https://drel.ai/openapi.json) — full OpenAPI 3.1 spec, including both
  the `ApiKeyAuth` and `ClerkOAuth` security schemes this document describes.
- [/.well-known/mcp.json](https://drel.ai/.well-known/mcp.json) and
  [/.well-known/mcp/server-card.json](https://drel.ai/.well-known/mcp/server-card.json) —
  MCP server discovery.
- [/developers](https://drel.ai/developers) — quickstart, endpoint reference, error codes.