---
title: "OAuth Scopes"
description: "Understand available OAuth scopes, how access is enforced, and how to request the right permissions for your integration."
canonical: https://developer.billabex.com/en/guides/scopes/
lang: en
alternate: https://developer.billabex.com/fr/guides/scopes/
last-updated: 2026-10-03
---

# OAuth Scopes

> Understand available OAuth scopes, how access is enforced, and how to request the right permissions for your integration.

Source: https://developer.billabex.com/en/guides/scopes/
Language: English (en)
French version: https://developer.billabex.com/fr/guides/scopes/

OAuth scopes define what your application is allowed to do after a user grants access. This guide explains how scope authorization works in Billabex and how to choose the right scope set.

## Overview

At a high level, scopes work like this:

1. Your app requests scopes during the OAuth authorization step.
2. The user approves those permissions.
3. Billabex issues tokens containing the granted scopes.
4. Each API endpoint checks scopes before executing the request.

## Key Concepts

- **Space-separated values**: Scopes are requested as a space-separated string.
- **Least privilege**: Request only what your integration needs.
- **Read vs write**: Most resource scopes follow `:read` (read-only) and `:all` (read/write) patterns.
- **OR authorization logic**: If an endpoint allows multiple scopes, having **one** allowed scope is enough.
- **No scope escalation on existing token**: To add permissions, you must re-run OAuth and request broader scopes.

## Available Scopes

### OpenID Connect (OIDC)

Use these scopes when you need user identity claims.

| Scope     | Purpose                                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `openid`  | Enables OIDC and ID token issuance                                                                                             |
| `profile` | Adds profile claims and manages the current user's avatar and [notification preferences](/en/guides/notification-preferences/) |
| `email`   | Adds email claims (`email`, `email_verified`)                                                                                  |

### Invoicing

| Scope               | Access Level | Representative Endpoints                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoices:read`     | Read-only    | <ul><li><code>GET /invoices</code></li><li><code>GET /invoices/:invoiceId</code></li></ul>                                                                                                                                                                                                                                                                                                                |
| `invoices:all`      | Full access  | <ul><li><code>POST /invoices</code></li><li><code>PUT /invoices/:invoiceId/paid-amount</code></li><li><code>PUT /invoices/:invoiceId/payment-schedule</code></li><li><code>PUT /invoices/:invoiceId/dunning-block</code></li><li><code>DELETE /invoices/:invoiceId/dunning-block</code></li><li><code>PUT /invoices/:invoiceId/due-date</code></li><li><code>DELETE /invoices/:invoiceId</code></li></ul> |
| `credit-notes:read` | Read-only    | <ul><li><code>GET /credit-notes</code></li><li><code>GET /credit-notes/:creditNoteId</code></li></ul>                                                                                                                                                                                                                                                                                                     |
| `credit-notes:all`  | Full access  | <ul><li><code>POST /credit-notes</code></li><li><code>DELETE /credit-notes/:creditNoteId</code></li><li><code>POST /credit-allocations</code></li></ul>                                                                                                                                                                                                                                                   |
| `accounts:read`     | Read-only    | <ul><li><code>GET /accounts</code></li><li><code>GET /accounts/:accountId</code></li><li><code>GET /accounts/:accountId/contacts</code></li><li><code>GET /accounts/:accountId/portal-link</code></li></ul>                                                                                                                                                                                               |
| `accounts:all`      | Full access  | <ul><li><code>POST /accounts</code></li><li><code>PUT /accounts/:accountId</code></li><li><code>DELETE /accounts/:accountId</code></li><li><code>POST /accounts/:accountId/portal-link</code></li><li>Contact management</li></ul>                                                                                                                                                                        |

### Dunning & Communications

| Scope                 | Access Level | Representative Endpoints                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `communications:read` | Read-only    | <ul><li><code>GET /outgoing-email-communications</code></li><li><code>GET /incoming-email-communications</code></li><li><code>GET /accounts/:accountId/outgoing-message-communications/:communicationId</code></li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `dunning:manage`      | Full access  | <ul><li><code>GET /accounts/:accountId/dunning</code></li><li><code>PUT /accounts/:accountId/dunning/preferences</code></li><li><code>POST /accounts/:accountId/dunning/pause</code></li><li><code>POST /accounts/:accountId/dunning/resume</code></li><li><code>POST /accounts/:accountId/dunning/payment-date-request/withdraw</code></li><li><code>PUT /outgoing-email-communications/:communicationId</code></li><li><code>POST /accounts/:accountId/outgoing-message-communications/preview</code></li><li><code>POST /accounts/:accountId/outgoing-message-communications</code></li><li>All read communication endpoints</li></ul> |

### Account Tasks

Account tasks are created by the Billabex agent when user input is required. These scopes control access to account task endpoints.

| Scope        | Access Level | Representative Endpoints                                                                                                                                                                                    |
| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tasks:read` | Read-only    | <ul><li><code>GET /account-tasks</code></li><li><code>GET /account-tasks/:accountTaskId</code></li></ul>                                                                                                    |
| `tasks:all`  | Full access  | <ul><li><code>POST /account-tasks/:accountTaskId/cancel</code></li><li><code>POST /account-tasks/:accountTaskId/close</code></li><li><code>POST /account-tasks/:accountTaskId/interactions</code></li></ul> |

### Platform

| Scope                | Access Level | Representative Endpoints                                                                                                                                                                                                                                                           |
| -------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizations:read` | Read-only    | <ul><li><code>GET /organizations</code></li><li><code>GET /organizations/:organizationId</code></li><li><code>GET /organizations/:organizationId/members</code></li></ul>                                                                                                          |
| `organizations:all`  | Full access  | <ul><li><code>PUT /organizations/:organizationId</code></li><li><code>PUT /organizations/:organizationId/settings</code></li><li><code>POST /organizations/:organizationId/invitations</code></li><li><code>DELETE /organizations/:organizationId/members/:userId</code></li></ul> |

### MCP (Model Context Protocol)

These scopes are used by MCP clients connecting to the Billabex MCP server.

| Scope       | Access Level | Description                                                     |
| ----------- | ------------ | --------------------------------------------------------------- |
| `mcp:read`  | Read-only    | Allow MCP tools to read invoices, accounts, and communications. |
| `mcp:write` | Write access | Allow MCP tools to create, update, and delete data.             |

See **[MCP Server](/en/guides/mcp/)** for the full list of available tools and resources.

### Write nature

| Scope  | Access Level | Description                                                            |
| ------ | ------------ | ---------------------------------------------------------------------- |
| `sync` | None         | Declares this client an automated synchronization. Grants no endpoint. |

`sync` is the one scope that does not unlock anything. It tells Billabex that the writes coming from this client are machine writes rather than a person's, and that changes how contact data is merged:

- **A contact's `fullName` and `language` stay with whoever typed them.** If a person set either field in the web app or through any non-`sync` client, a `sync` client can no longer overwrite it. It can still seed a field nobody has set.
- **Phone numbers land in their own pile.** Every number carries an `origin`: `Manual` for a number a person entered, `Connector` for a number written by a synchronization, which now includes yours once you hold `sync`. Writing `phones` replaces only your own pile and leaves the other intact, so a synchronization and the customer's team stop erasing each other.
- **An unreadable number is skipped instead of failing the request.** A number that cannot be normalized (no `countryCode` on a national number, free text such as `"see Jean"`) is dropped and reported, rather than turning the whole update into a `400`. Without `sync`, it stays a `400`, because a person needs to be told their input is wrong.

What is refused or dropped comes back in a `warnings` array on the contact response, each entry naming the `field`, the ignored `value` and a `reason` of `MANUALLY_SET` or `UNPARSEABLE`. The key is absent when there is nothing to report. Read it: without it, a refused write is indistinguishable from a write that changed nothing, since both answer `200` with the contact as it stands.

Because `sync` only takes rights away, it is self-declared: request it like any other scope, no extra approval step. Do not request it for an integration a person drives by hand, or that person's edits will be filed as machine writes.

```text
openid email accounts:all invoices:all sync
```

## Requesting Scopes

Include scopes in the OAuth authorization request:

```javascript
const authUrl = new URL('https://next.billabex.com/api/oauth/authorize');
authUrl.searchParams.append(
  'scope',
  'openid email invoices:read accounts:read',
);
```

## Recommended Scope Sets

### Read-only reporting integration

```text
openid email invoices:read credit-notes:read accounts:read
```

### Invoice management workflow

```text
openid email invoices:all credit-notes:all accounts:read
```

### Dunning assistant integration

```text
openid email invoices:read accounts:read communications:read dunning:manage
```

### Organization administration tool

```text
openid email organizations:all
```

### Account task management integration

```text
openid email tasks:all accounts:read
```

### MCP client integration

```text
mcp:read mcp:write
```

See **[MCP Server](/en/guides/mcp/)** for available tools and resources.

## Authorization Behavior

### OR Logic on Endpoints

When an endpoint allows multiple scopes, any one accepted scope grants access.

Example:

- Endpoint accepts `invoices:read` **or** `invoices:all`
- Token with only `invoices:read` is authorized

### Superset Behavior

If you already have `resource:all`, you don’t need `resource:read` separately for the same resource.

## Common Scope Errors

### `invalid_scope`

Happens when a requested scope is unknown or malformed.

```json
{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid or unknown"
}
```

### `insufficient_scope`

Happens when your token does not include a required scope for the endpoint.

```json
{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "insufficient_scope"
}
```

## Security Best Practices

- Request the minimum scope set required for your integration.
- Start with read scopes and expand only when needed.
- Re-authorize users when your app requires new permissions.
- Audit requested scopes regularly as features evolve.

## Next Steps

- **[Getting Started](/en/guides/getting-started/)** - Quick start integration flow
- **[OAuth Authentication](/en/guides/oauth/)** - Full OAuth 2.1 + PKCE guide
- **[API Reference](/en/api-reference/)** - Endpoint-by-endpoint details

## Support

Questions about scopes and permissions? Contact us via the [website contact form](https://billabex.com).

## Customer payment follow-up preference

`PUT /api/public/v1/accounts/:accountId/dunning/preferences` accepts
`{ "preventPreDueReminders": true }` with the `dunning:manage` scope.
MCP exposes `set-account-dunning-preferences` with `accountId` and
`preventPreDueReminders`, under `mcp:write`.

The preference is permanent and disabled by default. Automatic reminders omit invoices
and installment amounts that are not due yet. The due date itself is included, while
longer organization delays still apply. Send `false` to restore the organization's
behavior without lifting any suspension.
The status returns `preventPreDueReminders`, `invoiceDueEligibleAt` and, during this wait,
`silenceReason: "invoice-due-date-pending"`. The date is a reassessment, not a promised send time.

---

Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json.
Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.