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

# OAuth clients

> Create account-scoped OAuth 2.0 applications and use authorization code or client credentials flows.

Rookoo issues OAuth 2.0 access tokens as JWTs (RS256). Account administrators can register OAuth clients under **Settings → Integrations → OAuth Applications**. Super admins can also manage global clients (no account) in the super admin console.

Account-scoped clients are tied to the account that created them. Only administrators of that account can list, update, or delete them.

## Scopes

| Scope | Default | Description |
| - | - | - |
| `profile` | Yes | Basic user identity (id, email, name) |
| `accounts` | No | Account IDs the user belongs to |
| `read` | No | Read access to Application API resources |
| `write` | No | Write access to Application API resources |

## Create a client in the portal

1. Open **Settings → Integrations → OAuth Applications**.
2. Click **New OAuth App**.
3. Set a name, redirect URI, and scopes.
4. Copy the **Client ID** (`uid`) and **Client Secret**. The secret is shown in the app details and can be regenerated later.

Redirect URIs must use `https`, a custom scheme (for native apps), or `http` on `localhost` / `127.0.0.1`. Public (non-confidential) clients must use PKCE.

## Create a client via API

Requires an administrator user access token:

```bash theme={null}
curl -X POST https://app.rookoo.ai/api/v1/accounts/1/oauth_applications \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oauth_application": {
      "name": "My Integration",
      "redirect_uri": "https://myapp.com/oauth/callback",
      "scopes": "profile read write",
      "confidential": true
    }
  }'
```

Response includes `uid` (client id) and `secret`.

Regenerate the secret:

```bash theme={null}
curl -X POST https://app.rookoo.ai/api/v1/accounts/1/oauth_applications/1/regenerate_secret \
  -H "api_access_token: YOUR_ACCESS_TOKEN"
```

## Authorization code flow

### 1. Send the user to authorize

```
https://app.rookoo.ai/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth%2Fcallback&response_type=code&scope=profile+read&code_challenge=CHALLENGE&code_challenge_method=S256
```

The user must be signed in to the portal. After approval they are redirected with `?code=...`.

### 2. Exchange the code for tokens

```bash theme={null}
curl -X POST https://app.rookoo.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "redirect_uri=https://myapp.com/oauth/callback" \
  -d "code_verifier=VERIFIER"
```

Example response:

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "...",
  "scope": "profile read",
  "created_at": 1710000000
}
```

Access tokens expire after 2 hours. Use the refresh token to obtain a new access token without re-prompting the user.

### 3. Call the API

```bash theme={null}
curl https://app.rookoo.ai/api/v1/accounts/1/conversations \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

OAuth JWTs use the `Authorization: Bearer` header (not `api_access_token`). The token user must be a member of the account in the path.

## Client credentials flow

For machine-to-machine clients that do not act as a user. Prefer authorization code when the integration needs user permissions.

```bash theme={null}
curl -X POST https://app.rookoo.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "scope=profile+read"
```

## Refresh tokens

```bash theme={null}
curl -X POST https://app.rookoo.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET"
```

## Discovery endpoints

| URL | Purpose |
| - | - |
| `/.well-known/oauth-authorization-server` | Authorization server metadata |
| `/.well-known/oauth-protected-resource` | Protected resource metadata (MCP and API) |
| `/.well-known/jwks.json` | JWT verification keys |
| `POST /oauth/register` | Dynamic client registration |

## Manage clients via API

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v1/accounts/{account_id}/oauth_applications` | List clients |
| `POST` | `/api/v1/accounts/{account_id}/oauth_applications` | Create client |
| `GET` | `/api/v1/accounts/{account_id}/oauth_applications/{id}` | Show client |
| `PATCH` | `/api/v1/accounts/{account_id}/oauth_applications/{id}` | Update redirect URI / scopes |
| `DELETE` | `/api/v1/accounts/{account_id}/oauth_applications/{id}` | Delete client |
| `POST` | `/api/v1/accounts/{account_id}/oauth_applications/{id}/regenerate_secret` | Rotate secret |

All of these routes require an administrator of `{account_id}`.