Key scopes

A scope names a part of the API that a key may call. Every endpoint of the API reference declares the one scope it needs. A request with a key that lacks it is refused with 403 and the code api_keys.scope, before anything is read or changed.

Scopes say which operations a key may call. The key's role, data profile and collections still decide which objects those operations see: a key with cards:write and the viewer role cannot change cards, and a key limited to one collection does not see the others.

Scopes

Scope	Allows
`cards:read`	Read cards, collections and folders.
`cards:write`	Create, change and delete cards, collections and folders.
`search`	Search the knowledge base (`POST /v1/search`).
`ask`	Ask the assistant (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Write into the custom sources of the organization: syncs, batches and deletions, and read their state. Creating a source and its keys needs `admin`.
`webhooks:manage`	Manage webhook endpoints and read the event feed (`GET /v1/webhook-events`). Both also need the `admin` role.
`users:read`	Read users and groups.
`users:write`	Change users and groups.
`analytics:read`	Read analytics.
`audit:read`	Read the audit log.
`finance:read`	Read financial reports, invoices and payments.
`catalog:read`	Read the service catalog.
`files:read`	Read generated files, such as exported answers.
`files:write`	Change and delete generated files.
`permissions:manage`	Grant and revoke permissions on objects.
`admin`	The settings of the organization and its API keys. A key with `admin` has every other scope too.

Search and questions are reads by meaning: a key that may only read can still search and ask.

Choosing scopes

Grant the scopes that an integration uses and nothing else:

Integration	Scopes
Q&A bot in a chat tool	`search`, `ask`
Import from your document system	`cards:write` (cards API) or `import:write` (custom source)
Data warehouse export	`cards:read`, `users:read`, and `webhooks:manage` for the event feed
Provisioning users from your HR system	`users:write`

Pass the list when you create the key:

curl -X POST https://api.example.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

Earlier scopes

Keys created before scopes were split keep working. Their scopes read, write and admin stand for these sets:

Earlier scope	Means
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	everything in `read`, plus `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	every scope

A key created without explicit scopes gets them from its role: admin gets admin; editor and verifier get write; viewer gets read.

Seeing the scopes of a key

GET /v1/me returns the scopes of the key that makes the request, whatever scopes it has. For a key created without explicit scopes, these are the earlier scopes of its role, such as read and write; the table above shows what they stand for. When an operation fails with api_keys.scope, error.message names the scope that was missing.