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

# OAuth 2.0

> Let an agent act on a user's behalf with authorization-code + PKCE.

Cruq AI is an OAuth 2.0 authorization server, so an external agent or app can
act on a user's behalf without ever handling their API key. It supports the
authorization-code grant with PKCE, refresh tokens, and dynamic client
registration, and MCP clients can discover it automatically.

## Endpoints

Discovery metadata (RFC 8414) lists everything:

```
GET https://api.cruq.ai/.well-known/oauth-authorization-server
```

| Purpose                                | Endpoint                              |
| -------------------------------------- | ------------------------------------- |
| Authorize (user consent)               | `https://app.cruq.ai/oauth/authorize` |
| Token                                  | `https://api.cruq.ai/oauth/token`     |
| Dynamic client registration (RFC 7591) | `https://api.cruq.ai/oauth/register`  |
| Revoke (RFC 7009)                      | `https://api.cruq.ai/oauth/revoke`    |

## Flow

1. **Register a client** (once). Public clients use PKCE and no secret:

   ```bash theme={null}
   curl -X POST https://api.cruq.ai/oauth/register \
     -H "Content-Type: application/json" \
     -d '{"client_name":"My Agent","redirect_uris":["https://myagent.example/callback"],"token_endpoint_auth_method":"none"}'
   ```

   The response contains a `client_id` (and a `client_secret` for confidential clients).

2. **Send the user to authorize.** Generate a PKCE `code_verifier` / `code_challenge`, then redirect the user to:

   ```
   https://app.cruq.ai/oauth/authorize?response_type=code
     &client_id=<client_id>
     &redirect_uri=<your redirect_uri>
     &code_challenge=<S256 challenge>&code_challenge_method=S256
     &state=<random>
   ```

   The user signs in (if needed), sees a consent screen for their workspace, and approves. Cruq AI redirects back to your `redirect_uri` with `?code=...&state=...`.

3. **Exchange the code for tokens:**

   ```bash theme={null}
   curl -X POST https://api.cruq.ai/oauth/token \
     -d grant_type=authorization_code \
     -d client_id=<client_id> \
     -d redirect_uri=<your redirect_uri> \
     -d code=<code> \
     -d code_verifier=<verifier>
   ```

   Returns `access_token` (`cruq_at_...`), `refresh_token`, `expires_in`, and `scope`.

4. **Call the API** with the access token, exactly like an API key:

   ```bash theme={null}
   curl https://api.cruq.ai/v1/agents -H "Authorization: Bearer cruq_at_..."
   ```

   Access tokens also work against the [MCP server](/docs/mcp). Refresh with
   `grant_type=refresh_token` when the access token expires.

## Scopes

Today a single `api` scope grants full access to the user's workspace, the same
reach as an API key. Finer-grained scopes may be added later; tokens already
carry a scope list.