> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.brevo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server.

# Scopes

Scopes declare what a Brevo user is consenting your app to do on their behalf. You include them in the authorization request, the user sees them on the consent screen, and they're embedded in the issued access token.

## Naming convention

```
{resource}[.{sub-resource}]:{action}
```

* `resource` — the API area (e.g. `contacts`, `crm`, `webhooks`)
* `sub-resource` — optional, used to split large areas (e.g. `transactional.email`, `campaigns.sms`)
* `action` — either `read` (GET access) or `write` (create/update/delete access)

`:write` does **not** imply `:read`. If your app needs to both read and modify a resource — for example, list contacts before updating them — request both scopes.

## Scope catalog

Each scope's name, what it grants, and the API paths it authorizes. Paths are **prefixes** — `/contacts` covers every endpoint under `/contacts/...`. `:read` authorizes `GET` requests on those paths; `:write` authorizes `POST`, `PUT`, `PATCH` and `DELETE` on the same paths.

Scopes are grouped by category — the same grouping returned by `brevo app available-scopes`. Use the filter to find a scope by name, description or endpoint.

Prefer the terminal? Run `brevo app available-scopes --web` to browse this same catalog in a local page, or `brevo app available-scopes --json` for the raw list.

## Requesting scopes

Scopes go in the `scope` query parameter of the authorization request, space-separated and URL-encoded.

```
https://oauth.brevo.com/realms/partner/oauth/authorize
  ?response_type=code
  &client_id=<CLIENT_ID>
  &redirect_uri=<REDIRECT_URI>
  &scope=contacts%3Aread%20contacts%3Awrite%20transactional.email%3Awrite
  &state=<RANDOM_STATE>
```

Decoded, `scope=contacts:read contacts:write transactional.email:write`.

The user sees a consent screen listing the human-readable name and description of each requested scope before authorizing.

## Inspecting scopes in a token

Every issued access token is a signed JWT and includes a `scope` claim — a space-separated string of the scopes granted to that specific token. Decode the JWT or call the introspection endpoint to verify what a token can do.

```bash
curl --request POST \
  --url https://oauth.brevo.com/realms/partner/oauth/introspect \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user '<CLIENT_ID>:<CLIENT_SECRET>' \
  --data-urlencode 'token=<ACCESS_TOKEN>'
```

Response (RFC 7662):

```json
{
  "active": true,
  "scope": "contacts:read contacts:write transactional.email:write",
  "client_id": "<CLIENT_ID>",
  "exp": 1735689600,
  "iat": 1735686000,
  "sub": "user-uuid",
  "token_type": "Bearer"
}
```

## Errors

| HTTP status | `error`           | When                                                                                   |
| ----------- | ----------------- | -------------------------------------------------------------------------------------- |
| 400         | `invalid_scope`   | The requested scope isn't in the catalog, or exceeds the scopes registered on your app |
| 400         | `invalid_request` | `scope` parameter is missing or malformed                                              |

The `error_description` field carries the specific reason — for example, `requested scope exceeds scopes allowed for this client`.

## Discovering scopes programmatically

The OAuth server publishes standard discovery metadata at:

```
https://oauth.brevo.com/realms/partner/.well-known/oauth-authorization-server
```

The `scopes_supported` field is sourced live from the catalog — this is the same list you get from `brevo app available-scopes`.

```bash
curl https://oauth.brevo.com/realms/partner/.well-known/oauth-authorization-server \
  | jq '.scopes_supported'
```

## Choosing scopes for your app

A few common combinations:

| Use case                                     | Scopes                                                              |
| -------------------------------------------- | ------------------------------------------------------------------- |
| Sync external contacts into Brevo            | `contacts:read contacts:write`                                      |
| Send transactional email on behalf of a user | `transactional.email:write`                                         |
| Read campaign performance                    | `campaigns.email:read campaigns.sms:read`                           |
| Build a CRM-side integration                 | `crm:read crm:write contacts:read`                                  |
| Webhook-driven integration                   | `webhooks:read webhooks:write` + the resource scopes you'll consume |

Start with the minimum your app needs. You can widen scopes later by editing `auth.scopes` in `app-config.json` and running `brevo app upload` — see the [CLI reference](/docs/cli-reference#brevo-app-upload).