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:

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.

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

Adding a new scope

Scopes are managed by AGO support. Email [e-mail] 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.