> ## Documentation Index
> Fetch the complete documentation index at: https://docs.animam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.1 Authorization

> Connect MCP clients to Animam using OAuth 2.1 + PKCE + dynamic client registration

Animam exposes an OAuth 2.1 authorization server fully conformant with the [MCP
authorization spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization).
Any MCP client (Claude Desktop, claude.ai Custom Connectors, Cursor, or your
own agent) can connect with zero manual configuration beyond the MCP server URL.

## How it works

The standard OAuth 2.1 Authorization Code flow with PKCE:

1. **Discovery** — client fetches `https://api.animam.ai/.well-known/oauth-authorization-server` to learn the endpoints
2. **Registration** — client POSTs to `/oauth/register` (RFC 7591 DCR) and receives a `client_id`
3. **Authorize** — client opens `/oauth/authorize?response_type=code&client_id=...&code_challenge=...&code_challenge_method=S256` in a browser
4. **Consent** — the tenant logs into animam.ai and approves the requested scopes
5. **Token exchange** — client POSTs the received code to `/oauth/token` with its PKCE verifier
6. **API calls** — client uses the returned `access_token` as `Authorization: Bearer <jwt>` on MCP requests

Access tokens live 15 minutes. Refresh tokens live 30 days and rotate on every use.

## Endpoints

| Endpoint                                  | Method | Purpose                                           |
| ----------------------------------------- | ------ | ------------------------------------------------- |
| `/.well-known/oauth-authorization-server` | GET    | RFC 8414 metadata                                 |
| `/.well-known/oauth-protected-resource`   | GET    | RFC 9728 resource metadata                        |
| `/.well-known/jwks.json`                  | GET    | Public key for JWT verification                   |
| `/oauth/register`                         | POST   | RFC 7591 Dynamic Client Registration              |
| `/oauth/authorize`                        | GET    | Authorization endpoint (redirects to consent UI)  |
| `/oauth/token`                            | POST   | Exchange code for access token + refresh rotation |
| `/oauth/revoke`                           | POST   | RFC 7009 token revocation                         |

All endpoints live on `https://api.animam.ai`.

## Scopes

| Scope                    | Description                             |
| ------------------------ | --------------------------------------- |
| `mcp:corpus:read`        | Read the tenant knowledge base (corpus) |
| `mcp:corpus:write`       | Create and modify corpus entries        |
| `mcp:segments:read`      | Read segments and slots                 |
| `mcp:segments:write`     | Create and modify segments and slots    |
| `mcp:tools:read`         | Read tool configuration                 |
| `mcp:tools:write`        | Create and modify tool configuration    |
| `mcp:conversations:read` | Read conversation history               |
| `mcp:visitors:read`      | Read visitor profiles and memory        |
| `mcp:settings:read`      | Read tenant settings                    |
| `mcp:settings:write`     | Modify tenant settings                  |
| `mcp:billing:read`       | Read plan usage and quota               |

Unknown scopes are silently filtered at consent time (RFC 6749 §3.3).

## Security

* **PKCE S256 mandatory** — no fallback to `plain` (OAuth 2.1 hardening)
* **Public clients only** — `token_endpoint_auth_method=none`, no client\_secret
* **Exact redirect\_uri match** — no wildcards, no substring matching
* **Single-use authorization codes** — replay attempts return `invalid_grant`
* **Strict refresh token rotation** — any reuse of a rotated refresh token triggers full-chain revocation
* **JWT access tokens RS256** — signed stateless, verifiable via JWKS, hashed in DB for early revocation
* **Rate limits** — 5/h/IP on DCR, 30/min on token/revoke, 20/min on authorize

## Example: register a client and start a flow

```bash theme={null}
# 1. Register
curl -X POST https://api.animam.ai/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["http://localhost:3000/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "mcp:corpus:read mcp:segments:read"
  }'
# → { "client_id": "animam-oauth-xxxxx", ... }

# 2. Generate PKCE verifier and challenge
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=+/' | cut -c1-43)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -binary -sha256 | openssl base64 -A | tr '+/' '-_' | tr -d '=')

# 3. Open authorize URL in browser (user logs in and approves)
echo "https://api.animam.ai/oauth/authorize?response_type=code&client_id=animam-oauth-xxxxx&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&scope=mcp%3Acorpus%3Aread&state=xyz&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

# 4. Exchange code for tokens
curl -X POST https://api.animam.ai/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "grant_type=authorization_code&code=<code>&redirect_uri=http://localhost:3000/callback&client_id=animam-oauth-xxxxx&code_verifier=$CODE_VERIFIER"
# → { "access_token": "eyJ...", "refresh_token": "...", "expires_in": 900, ... }
```

## Connecting from Claude Desktop

Add Animam as a remote MCP server in your Claude Desktop config. Claude Desktop
handles the entire OAuth flow (discovery + DCR + authorize + token exchange)
transparently — you just approve the consent screen once.

## Legacy ApiToken cohabitation

The MCP server accepts both OAuth JWT access tokens and legacy `ApiToken`
Bearer tokens (created from the tenant dashboard). OAuth is preferred for all
third-party integrations; `ApiToken` remains supported for internal scripts
and CI pipelines.

## Questions and feedback

For issues or feedback, contact the Animam team or open an issue at
[github.com/wellknownmcp/animam-ai](https://github.com/wellknownmcp/animam-ai).