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
tasks:read	Read board tasks, comments, statuses, labels, and assignable staff
tasks:write	Create / update / move / link / archive / delete and comment on board tasks
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

The tasks scopes only work when Tasks is enabled for your workspace and the user who granted access is an active staff user. See Tasks API.

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, no permissions are pre-selected. Choose at least one permission before granting access, or click Read only to select every available read permission.

What Claude Web requests

The consent screen lists the permissions Claude Web requested and pre-selects them. Review and adjust the selection before granting access.

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.

Read only selects every available read permission and clears all write permissions and Full Access. You can then adjust individual permissions before clicking Allow access. The same shortcut is available when creating or editing API keys.

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 → Developer → 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.