Scopes

Scopes control which API endpoints your token can access. They apply to both API Keys and OAuth2 tokens. Session cookie authentication (browser dashboard) has full access and is not subject to scopes.

Available Scopes

Invoices

Scope	Access
`invoices:read`	List invoices, get invoice details, generate PDF, preview PDF, download bulk PDF, export Excel, list recurring invoices, get recurring details, preview recurring
`invoices:write`	Create, update, delete, duplicate invoices. Issue, void, mark paid/sent, schedule. Send emails. Create/manage recurring invoices

Customers

Scope	Access
`customers:read`	List customers, get customer details, download CSV template
`customers:write`	Create, update, deactivate customers. Bulk create, bulk deactivate, CSV import, Holded import

Products

Scope	Access
`products:read`	List products, get product details, search products
`products:write`	Create, update, delete products. Bulk create, bulk delete

Configuration

Scope	Access
`configuration:read`	Read VeriFactu configuration, invoice customization options
`configuration:write`	Update VeriFactu configuration, tax configuration, language preferences

Billing Series

Scope	Access
`series:read`	List billing series
`series:write`	Create, update, delete series. Set default series

Taxes

Scope	Access
`taxes:read`	Read tax configuration, list available tax types

NIF Validation

Scope	Access
`nif:validate`	Validate Spanish NIFs against AEAT

Business Profiles

Scope	Access
`business_profiles:read`	List companies, get company details, download/check representation status, list company API keys
`business_profiles:write`	Create, update, delete companies. Generate/submit/cancel representations. Create/revoke company API keys

Scope Behavior

API Keys: Scopes are assigned when creating the key. Cannot be changed after creation.
OAuth2 tokens: Scopes are requested during authorization. The user consents to the requested scopes.
Session cookies: Full access, scopes are not enforced (dashboard users).

How Scopes Are Enforced

Each API endpoint requires one or more scopes. The required scope is documented in the API Reference for each operation.

If your token is missing a required scope:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "No tienes permiso para realizar esta accion"
  }
}

Requesting Scopes

API Keys

Select scopes when creating the key in Settings > API Keys.

OAuth2

Include the scope parameter in the authorization URL:

scope=invoices:read customers:read products:read

Request only what your application needs. Users see the requested scopes during consent.

Scopes

On this page