Scopes
The permissions an API key or OAuth token can hold, which endpoints each scope unlocks, and which scopes are granted by default.
Every API key and OAuth token carries a set of scopes. A request to an endpoint whose scope the credential doesn't hold is rejected with 403.
Available scopes
| Scope | Grants |
|---|---|
mentions:read | GET /v1/mentions, /v1/mentions/{id}, /v1/mentions/count |
listeners:read | GET /v1/listeners, /v1/listeners/{id} |
feeds:read | GET /v1/feeds, /v1/feeds/{id} |
org:read | GET /v1/organization/context, /v1/organization/usage |
search:read | Every /v1/data/* search endpoint (Twitter/X, LinkedIn and Hacker News). These spend credits from your organization. |
mentions:write | PATCH /v1/mentions/{id}/state. Also needs mentions:read. |
OAuth adds one more scope, offline_access, which issues a refresh token. See OAuth.
Defaults
- Read scopes (
mentions:read,listeners:read,feeds:read,org:read,search:read) are the default for new API keys. - Write scopes (
mentions:write) are always opt-in. Nothing grants them unless you pick them explicitly. - Note that
search:readis credit-metered, so holding it lets a credential spend your organization's search credits, not just read existing data.
Choosing scopes
- API keys: pick the scopes when you create the key under Integrations → API. See Authentication.
- OAuth: request scopes in the authorize call. They're shown to the customer on the consent screen, and a client can only request scopes it was registered with. See OAuth.
Request only what the integration needs. A key that only reads mentions shouldn't hold search:read or mentions:write.
Roles
A credential also can't do more than the member behind it. Each request checks both that the credential holds the scope and that the member who created or authorized it still has the matching permission in the organization. If they lose it, for example by being removed from the organization, requests fail with 403 even though the scope was granted.