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

# OAuth Scopes Reference

> Permissions an MCP client can request when authorizing through AGO's OAuth flow.

AGO's OAuth provider reuses the same scope taxonomy as long-lived API keys. A token's scopes determine which Public API v1 endpoints it can call.

## Scope format

Scopes follow the `resource:action` pattern, where `action` is `read` or `write`. A `write` scope implies the matching `read`.

| Scope                       | What it grants                                                                           |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `knowledge:read`            | Read documents, sources, translations, versions, and attachments                         |
| `knowledge:write`           | Create / update / delete / bulk-manage documents, sources, translations, and attachments |
| `conversations:read`        | Read threads, messages, feedback, and export conversations                               |
| `conversations:write`       | Update thread evaluation, admin comment, admin tags, and admin status                    |
| `tickets:read`              | Read tickets, messages, statuses, and statistics                                         |
| `analytics:read`            | Read dashboard analytics data                                                            |
| `agents_config:read`        | Read agents, tools, prompt templates, and UI resource templates                          |
| `agents_config:write`       | Create / update / delete agents, tools, prompt templates, and UI resource templates      |
| `accounts:read`             | Read organizations, their email domains, and users                                       |
| `custom_data_sources:read`  | Search and read rows from smart tables                                                   |
| `custom_data_sources:write` | Push (upsert) and delete rows in smart tables                                            |

For the live list specific to your tenant (scopes are stored per tenant DB), call:

```bash theme={null}
curl https://<your-tenant>.api.useago.com/.well-known/oauth-authorization-server \
  | jq '.scopes_supported'
```

## Default scope

If a client doesn't request specific scopes, AGO grants every available read scope (e.g. `knowledge:read`, `conversations:read`, `tickets:read`, `analytics:read`, `agents_config:read`, `accounts:read`, `custom_data_sources:read`) — read-only access. MCP clients that need to write data request the matching write scope explicitly so the consent screen surfaces it to the user.

## What Claude Web requests

Claude Web's connector requests a broad scope set covering both read and write — currently `knowledge:read`, `knowledge:write`, `conversations:read`, `tickets:read`, `agents_config:read`, `agents_config:write`, `analytics:read`, and `accounts:read`.

## Choosing scopes on the consent screen

The consent screen shows the full scope catalog as a checklist, with the scopes the client requested pre-selected. Before granting, you can uncheck any permission to grant less, or check others to grant more — the token carries exactly what you select, not what the client asked for.

If you grant fewer scopes than the client requested, the client is told the reduced set in its token response. Calls that need a permission you didn't grant return `403`. To change a connection's scopes later, revoke its token (Admin → Settings → OAuth Connections) and reconnect from the client.

<Note>
  Granting is staff-only — the same privilege bar as creating an API key. The connection is owned by the staff member who approved it.
</Note>

## Adding a new scope

Scopes are managed by AGO support. Email **[support@useago.com](mailto:support@useago.com)** with the resource you'd like the new scope to cover (read, write, or both) and the use case. Once added, the scope appears in `/.well-known/oauth-authorization-server` for your tenant immediately and becomes selectable on the consent screen.