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)

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.

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.

$
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):

1
{
2
  "active": true,
3
  "scope": "contacts:read contacts:write transactional.email:write",
4
  "client_id": "<CLIENT_ID>",
5
  "exp": 1735689600,
6
  "iat": 1735686000,
7
  "sub": "user-uuid",
8
  "token_type": "Bearer"
9
}

Errors

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.

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

Choosing scopes for your app

A few common combinations:

Start with the minimum your app needs. You can widen scopes later with brevo app update --scope <scope> — see the CLI reference.