---
updatedAt: 2026-03-31T07:49:40.000Z
agentTools:
  projectIndex: https://pennylane.readme.io/llms.txt
---

# Understand Scopes

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

<Callout icon="🔒" theme="default">
  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.
</Callout>

<Callout icon="💡" theme="default">
  Looking for Firm-specific scopes? See the Firm API Scopes page.
</Callout>

# How Scopes Work

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

```curl
# 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)   |

<Callout icon="🚧" theme="warn">
  If your token does not include the required scope, the API returns 403 Forbidden.
</Callout>

# 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                                         |
| `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                                 |
| `customer_invoice_templates:readonly` | 🔵 Read       | View customer invoice templates                                               |

## 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 |
| `purchase_requests:readonly` | 🔵 Read       | List and retrieve purchase requests                                           |
| `purchase_requests:all`      | 🟢 Read/Write | Import, list and retrieve purchase requests                                   |

## 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                                                                                                                                                       |
| `journals:readonly`        | 🔵 Read       | Retrieve and list journals                                                                                                                                                         |
| `journals:all`             | 🟢 Read/Write | Create, retrieve and list journals                                                                                                                                                 |
| `ledger_accounts:readonly` | 🔵 Read       | Retrieve and list ledger accounts                                                                                                                                                  |
| `ledger_accounts:all`      | 🟢 Read/Write | Create, update, retrieve and list ledger accounts                                                                                                                                  |
| `ledger_entries:readonly`  | 🔵 Read       | Retrieve and list ledger entries, list ledger entry lines of a ledger entry, list and retrieve ledger entry lines, list categories of a ledger entry line                          |
| `ledger_entries:all`       | 🟢 Read/Write | Create, update, retrieve and list ledger entries, categorize, letter and unletter ledger entry lines, list and retrieve ledger entry lines, list categories of a ledger entry line |

## 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 transactions, matched invoices, and category links                             |
| `transactions:all`             | 🟢 Read/Write | Create, categorize, update, view bank transactions, matched invoices, and category links |
| `bank_accounts:readonly`       | 🔵 Read       | View bank accounts                                                                       |
| `bank_accounts:all`            | 🟢 Read/Write | Create, retrieve and list bank accounts                                                  |
| `bank_establishments:readonly` | 🔵 Read       | View bank establishments                                                                 |

## 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:

```curl
GET /me
```

The response includes:

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

<Callout icon="✍️" theme="default">
  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.
</Callout>

# Tips for Developers

<Callout icon="💡" theme="default">
  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.
</Callout>

# 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                  |

<Callout icon="📘" theme="info">
  This list is current as of **October 2025**. Always refer to the <Anchor label="official Scopes Reference" target="_blank" href="https://pennylane.readme.io/reference/scopes">official Scopes Reference</Anchor> for the most up-to-date list of available scopes.
</Callout>