OAuth Scopes | Billabex Developer Portal

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:

Your app requests scopes during the OAuth authorization step.
The user approves those permissions.
Billabex issues tokens containing the granted scopes.
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 (`name`, `given_name`, `family_name`, `locale`)
`email`	Adds email claims (`email`, `email_verified`)

Invoicing

Scope	Access Level	Representative Endpoints
`invoices:read`	Read-only	`GET /invoices` `GET /invoices/:invoiceId`
`invoices:all`	Full access	`POST /invoices` `PUT /invoices/:invoiceId/paid-amount` `DELETE /invoices/:invoiceId`
`credit-notes:read`	Read-only	`GET /credit-notes` `GET /credit-notes/:creditNoteId`
`credit-notes:all`	Full access	`POST /credit-notes` `DELETE /credit-notes/:creditNoteId` `POST /credit-allocations`
`accounts:read`	Read-only	`GET /accounts` `GET /accounts/:accountId` `GET /accounts/:accountId/contacts`
`accounts:all`	Full access	`POST /accounts` `PUT /accounts/:accountId` `DELETE /accounts/:accountId` Contact/internal representative management

Dunning & Communications

Scope	Access Level	Representative Endpoints
`communications:read`	Read-only	`GET /outgoing-email-communications` `GET /incoming-email-communications` `GET /customer-outstanding-balances`
`dunning:manage`	Full access	`PUT /outgoing-email-communications/:communicationId` All read communication endpoints

Platform

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

Requesting Scopes

Include scopes in the OAuth authorization request:

const authUrl = new URL('[baseURL]/api/oauth/authorize');
authUrl.searchParams.append('scope', 'openid email invoices:read accounts:read');

Recommended Scope Sets

Read-only reporting integration

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

Invoice management workflow

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

Dunning assistant integration

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

Organization administration tool

openid email organizations:all

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.

{
  "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.

{
  "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 - Quick start integration flow
OAuth Authentication - Full OAuth 2.1 + PKCE guide
API Reference - Endpoint-by-endpoint details

Support

Questions about scopes and permissions? Contact us via the website contact form.