# Clera auth.md

How an agent authenticates against Clera. Audience: AI agents and MCP clients acting for a Clera user.

## Protected resource: the Clera MCP server

- Endpoint: https://mcp.getclera.com (Streamable HTTP)
- Protected resource metadata (RFC 9728): https://mcp.getclera.com/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414): https://mcp.getclera.com/.well-known/oauth-authorization-server
- Issuer: https://clerk.getclera.com
- Scopes: profile, email, offline_access
- Credential: OAuth 2.1 bearer access token in the Authorization header

## Registration

1. Register a client with dynamic client registration at the issuer's registration_endpoint. No pre-shared secret, no manual approval.
2. Run the authorization code flow with PKCE (S256). The user signs in with their Clera account in the browser.
3. Send the access token as `Authorization: Bearer <token>` on every MCP request. A missing or expired token gets a 401 with a WWW-Authenticate header that names the resource metadata URL.
4. Tools are filtered by the signed-in user's Clera role. Organization members see their own hiring surface; Clera admins see more.

Anonymous agents are not served: every tool call runs as a named Clera user.

## This website

https://www.getclera.com accepts the same Clerk access tokens on one endpoint:

- Protected resource metadata (RFC 9728): https://www.getclera.com/.well-known/oauth-protected-resource
- Authorization server metadata, mirrored from the issuer: https://www.getclera.com/.well-known/oauth-authorization-server
- `GET https://www.getclera.com/api/public/users/me` with `Authorization: Bearer <token>` returns the Clera user the token acts for: profile id, email, platform role and the token's scopes. Requires the `profile` scope. 401 responses carry `WWW-Authenticate: Bearer resource_metadata="..."`, a token without the scope gets 403 with `error="insufficient_scope"`, and a token for an account with no Clera profile gets 404. Organization membership and hiring tools stay on the MCP server.

Public pages need no auth. Other endpoints under /api serve Clera's own frontend and are not an agent surface. Partner-only endpoints under /api/public are API-key gated and issued by hand; ask at https://www.getclera.com/hire.

## Related

- MCP setup guide: https://www.getclera.com/mcp
- MCP docs (tools, prompts, access): https://www.getclera.com/mcp/docs
- Server card: https://www.getclera.com/.well-known/mcp/server-card.json
- API catalog: https://www.getclera.com/.well-known/api-catalog
- Security contact: https://www.getclera.com/.well-known/security.txt