Pennylane uses scopes to define what data your API token or OAuth app can access.

Each scope represents a specific permission, such as viewing invoices or creating products.

Scopes ensure your integrations follow the principle of least privilege, giving access only to the data and actions they truly need.

Use this page to explore all available scopes, understand their purpose, and determine which ones your token requires.

Before You Get Started

🔒
Scopes apply to both Company and Firm APIs, depending on how you authenticate:

Company tokens > Access a single company’s data.

Firm tokens > Access multiple client companies’ data.

OAuth apps > Request scopes dynamically during user consent.

💡
Looking for Firm-specific scopes? See the Firm API Scopes page.

How Scopes Work

Include scopes when generating an API token or during OAuth authorization.

# Example (OAuth 2.0 authorization)
scope=customers:all suppliers:readonly

Each scope follows the same pattern:

Format	Meaning
`resource:readonly`	🔵 Read-only access (GET endpoints only)
`resource:all`	🟢 Full access (read + write + delete)

🚧
If your token does not include the required scope, the API returns 403 Forbidden.

Scope Domains

Scopes are organized by business domain, following the same structure as the API Reference.

SALES (Customer Billing)

Customer Billing scopes give full control over sales documents, from quotes and invoices to SEPA mandates and recurring subscriptions.

Scope	Access	Description
`customers:readonly`	🔵 Read	View customers (company or individual)
`customers:all`	🟢 Read/Write	Create, update, and view customers — including individual and company records
`products:readonly`	🔵 Read	View products
`products:all`	🟢 Read/Write	Create, update, delete, and view products (including change events)
`customer_invoices:readonly`	🔵 Read	View customer invoices and matched transactions
`customer_invoices:all`	🟢 Read/Write	Create, update, and match customer invoices to transactions
`quotes:readonly`	🔵 Read	View sales quotes
`quotes:all`	🟢 Read/Write	Create, update, and view sales quotes
`e_invoices:all`	🟢 Read/Write	Import electronic invoices
`customer_mandates:readonly`	🔵 Read	View SEPA customer mandates
`customer_mandates:all`	🟢 Read/Write	Create, update, and view SEPA customer mandates
`billing_subscriptions:readonly`	🔵 Read	View billing subscriptions
`billing_subscriptions:all`	🟢 Read/Write	Create, update, and view billing subscriptions
`commercial_documents:readonly`	🔵 Read	View commercial documents
`commercial_documents:all,`	🟢 Read/Write	Create, update, and view commercial documents

PURCHASES (Supplier Billing)

Supplier Billing scopes give full control over supplier documents.

Scope	Access	Description
`suppliers:readonly`	🔵 Read	View suppliers
`suppliers:all`	🟢 Read/Write	Create, update, and view suppliers
`supplier_invoices:readonly`	🔵 Read	View supplier invoices and matched transactions
`supplier_invoices:all`	🟢 Read/Write	Create, update, validate, import, and match supplier invoices to transactions

ACCOUNTING

Accounting scopes are required for any synchronization of journal entries or exports.

Scope	Access	Description
`ledger`	🟢 Read/Write	Create, update, and view journals, ledger entries, and their attachments
`trial_balance:readonly`	🔵 Read	Retrieve trial balance
`exports:fec`	🔵 Read	Retrieve FEC (French fiscal export)
`exports:agl`	🔵 Read	Retrieve analytical general ledger export
`fiscal_years:readonly`	🔵 Read	View fiscal year information

ANALYTICS

Analytics scopes control access to analytical groupings used in accounting exports.

Scope	Access	Description
`categories:readonly`	🔵 Read	View analytical categories and category groups
`categories:all`	🟢 Read/Write	Create, update, delete, and view analytical categories and category groups

BANKING

Banking scopes allow you to retrieve transactions, reconcile invoices, and view categorized movements.

Scope	Access	Description
`transactions:readonly`	🔵 Read	View bank accounts
`bank_accounts:readonly`	🔵 Read	View bank transactions, matched invoices, and category links

CORE / SHARED

Core scopes are shared across multiple modules - for example, attachments linked to invoices or journal entries.

Scope	Access	Description
`file_attachments:readonly`	🔵 Read	View attached files
`file_attachments:all`	🟢 Read/Write	Upload, update, delete, and view file attachments

Testing Your Scopes

You can verify both your token’s scopes and your user/company context with:

GET /me

The response includes:

your company ID and user information,
and the list of active scopes for your token.

✍️
This endpoint does not require a dedicated scope. All valid tokens can access it to confirm authentication and scope configuration. There are currently no public endpoints to manage users programmatically — user management is handled directly in the Pennylane interface.

Tips for Developers

💡
For Company tokens, select scopes in your dashboard under Settings > Connectivity > Developers. For Firm tokens, go to Settings > Firm Tokens. For OAuth apps, include all required scopes in your scope parameter.

Troubleshooting

Error	Cause	Fix
`403 Forbidden`	Missing or invalid scope	Regenerate token with required scopes
`401 Unauthorized`	Invalid token	Check Authorization header
`422 Unprocessable Entity`	Malformed request body	Validate JSON schema

📘
This list is current as of October 2025. Always refer to the official Scopes Reference for the most up-to-date list of available scopes.