# API scopes and permissions (https://snitchfeed.com/docs/api/scopes)

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 [#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](/docs/api/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](/docs/api/oauth).

## Defaults [#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:read` is credit-metered: holding it lets a credential spend your organization's credits, not just read stored data.

## Choosing scopes [#choosing-scopes]

- **API keys:** pick scopes when you create the key under **Integrations → API**. See [Authentication](/docs/api/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](/docs/api/oauth).

Request only what the integration needs. A key that only reads mentions should not hold `search:read` or `mentions:write`.

## Roles [#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 [#related]

- [API authentication](/docs/api/authentication): create a key and choose its scopes
- [API OAuth 2.0](/docs/api/oauth): request scopes for an integration
- [SnitchFeed API](/docs/api/introduction): endpoints and error codes