API scopes and permissions
The six SnitchFeed API scopes, the endpoints each one unlocks, which are on by default for new keys, and how the user's workspace role also limits access.
Last updated
Every API key and OAuth token carries a set of scopes. A request to an endpoint whose scope the credential does not hold is rejected with 403 forbidden.
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/* endpoint (X, LinkedIn and Hacker News). These spend your organization's credits |
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 ticked by default for new API keys. - Write scopes (
mentions:write) are always opt-in. Nothing grants them unless you pick them. search:readis credit-metered: holding it lets a credential spend your organization's credits, not just read stored data.
Choosing scopes
- API keys: pick scopes when you create the key under Integrations → API. See Authentication.
- OAuth: request scopes in the authorize call. The customer sees them 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 should not hold search:read or mentions:write.
Roles
A credential can't do more than the workspace member behind it. Each request checks that the credential holds the scope and that the member who created or authorized it still has access to the workspace's data. If they lose it, for example because they were removed from the workspace, requests fail with 403 even though the scope was granted.
Related
- API authentication: create a key and choose its scopes
- API OAuth 2.0: request scopes for an integration
- SnitchFeed API: endpoints and error codes
Authentication
Authenticate SnitchFeed API requests with a Bearer API key or OAuth token: create, scope and revoke keys under Integrations, API, plus 401 and 403 responses.
Rate limits
SnitchFeed API limits per organization: 20 requests a minute per search surface, 60 for org data, 2 in flight at once, plus headers and 429s.