Need the OAuth scope required for each endpoint? Check the endpoints access table.OAuth scopes define what your application is allowed to do on behalf of a Qonto user. When a user connects their account, they see a consent screen listing the exact permissions your application is requesting. Only request the scopes you actually need.
Building a new integration? Before selecting scopes, make sure you’ve chosen the right use case for your application. If your integration uses sensitive scopes, check the approval requirements by use case before going to production.
Scope selection guidance
Do you need organization.read?
organization.read is one of the most commonly requested scopes, but also the most broad. Before requesting it, consider whether a narrower scope covers your actual need:
| If you need to… | Use this scope instead |
|---|---|
| Download supplier or client invoice PDFs | attachment.read — see workaround below |
| Read a user’s personal identity and role | membership.read |
| List all members of an organization | organization.read is required — membership.read only retrieves the authenticated user’s own membership |
| List transactions | organization.read is required |
| Access balances or IBANs | organization.read is required |
Do you need beneficiary.trust or payment.write for beneficiary management?
These two scopes cover different sides of SEPA beneficiary trust management and are often needed together:
| If you need to… | Use this scope |
|---|---|
| Mark a beneficiary as trusted (to enable automated transfers without SCA) | beneficiary.trust — Embed partners only |
| Untrust a beneficiary | payment.write |
| Both trust and untrust beneficiaries | Request both scopes |
Trusting a beneficiary lets your integration initiate transfers to that beneficiary without requiring SCA on every transaction. The actual transfer still requires
payment.write.Fetching invoice PDFs without organization.read
If your only requirement is downloading supplier or client invoice PDFs, you can avoid the sensitive organization.read scope entirely by using attachment.read.
How it works:
- Fetch the supplier invoice (
supplier_invoice.read) or client invoice (client_invoices.read). The response includes anattachment_idfield. - Call
GET /v2/attachments/{id}using theattachment.readscope. - The response includes a pre-signed
urlyou can use to download the PDF directly.
This approach only works when fetching invoice PDFs is your sole need. If you also need transaction data, account balances, or organization details,
organization.read is still required.For client invoices in Factur-X format, the PDF may need to be regenerated before download. If the
url is not immediately available in the response, retry the request after a short delay. Learn moreAvailable scopes
Consent messages shown in the table below are displayed to Qonto users on the consent screen during the OAuth authorization flow. Scopes marked NA in the consent message column do not display a permission entry on the consent screen.| Scope | Consent message | Endpoints |
|---|---|---|
organization.read Sensitive | Get and export info about your balance, IBAN, transactions, organization and team | - Beneficiaries: List SEPA beneficiaries, Retrieve a SEPA beneficiary - Labels: List labels, Retrieve a label - Memberships: List memberships - Organization: Retrieve the authenticated organization and list bank accounts - Transactions: List transactions, Retrieve a transaction - Requests: List requests - Statements: Retrieve a statement, List statements - Business Accounts: List business accounts, Retrieve a business account, Download the IBAN certificate - SEPA Transfers: List SEPA transfers, Retrieve a SEPA transfer - SEPA Recurring Transfers: List SEPA recurring transfers, Retrieve a SEPA recurring transfer - SEPA Bulk Transfers: List SEPA bulk transfers, Retrieve a SEPA bulk transfer |
payment.write Sensitive | Remove beneficiaries from trusted beneficiaries Make payments to trusted beneficiaries Make payments to any beneficiary (requiring identity verification from the phone you’ve paired with Qonto) | - Beneficiaries: Add a SEPA beneficiary, Update a SEPA beneficiary, Untrust SEPA beneficiaries - SEPA Transfers: Create a SEPA transfer, Cancel a SEPA transfer, Download a SEPA transfer proof - SEPA Recurring Transfers: Create a SEPA recurring transfer, Cancel a SEPA recurring transfer - SEPA Bulk Transfers: Create a SEPA bulk transfer |
internal_transfer.write Sensitive | NA | Create an internal transfer |
international_transfer.write Sensitive | Make international transfers | - Transfers: List International transfer requirements, Create International Transfers - Beneficiaries: List requirements for an international beneficiary, Update an international beneficiary, Create an international beneficiary, Delete an international beneficiary - Quotes: Create a new international transfer quote |
attachment.read | Get and export attachments | - Attachments: Retrieve an attachment - Attachments in transactions: List attachments for a transaction |
attachment.write | Upload attachments Remove attachments from transactions | - Attachments: Upload an attachment - Attachments in transactions: Upload an attachment to a transaction, Remove all attachments from a transaction, Remove an attachment from a transaction |
membership.read | Get and export your personal data, e.g. identity information, contact details (including your address), and role | Retrieve the authenticated membership |
membership.write | Invite new members to teams | Create a membership |
supplier_invoice.read | Get the list of supplier invoices | List supplier invoices, Retrieve a supplier invoice |
supplier_invoice.write | Generate supplier invoices | Create supplier invoices |
client_invoices.read | Get the list of client invoices, quotes and credit notes Get all the details about client invoices, credit notes, quotes and clients | - Client invoices: List client invoices, Retrieve a client invoice - Credit notes: List credit notes, Retrieve a credit note |
client_invoice.write | Create and update client invoices, quotes and add clients | Create a client invoice, Update a client invoice |
product.read | Get the list of products | List products |
product.write | Create products | Create a product |
client.read | Get all the details about clients | Retrieve a client, List clients |
client.write | Create, update and delete clients | Create a client, Update a client, Delete a client |
team.read | Get the list of teams | List teams |
team.write | NA | Create a team |
card.read | Get all the details about your cards | List cards, Retrieve a card iframe url, List card appearances |
card.write | Create new cards | Create a card, Report a physical card as lost, Report a physical card as stolen, Discard a card, Lock a card, Unlock a card |
insurance_contract.read | Share your insurance policy details with Qonto | Retrieve an insurance contract |
insurance_contract.write | Sync your insurance policy details with Qonto | Create an insurance contract, Update an insurance contract, Upload a document to an insurance contract, Remove a document from an insurance contract |
request_review.write | NA | Approve a request, Decline a request |
request_transfers.write | NA | Create multi transfer request |
request_cards.write | NA | Create a flash card request, Create a virtual card request |
bank_account.write | NA | Create a business account, Update a business account, Close a business account |
beneficiary.trust Sensitive Embed partners only | Mark beneficiaries as trusted or remove them from trusted beneficiaries | Trust SEPA beneficiaries |
payment_link.write | Create and manage payment links | - Connect to the payment links provider - Create a payment link - Deactivate a payment link |
payment_link.read | View payment links and payment activity | - Get the connection status - List payment links - Retrieve a payment link - List payments for a payment link - List available payment methods |
einvoicing.read | Get e-invoicing settings | Retrieve e-invoicing settings |
user_organization.read | View the organizations the user grant access to | List user organizations |
webhook | NA | - List webhook subscriptions - Create a new webhook subscription - Get a webhook subscription - Update a webhook subscription - Delete a webhook subscription |
sepa_direct_debit.read | View your SEPA Direct Debit payments View and manage your SEPA Direct Debit payments (when together with sepa_direct_debit.write) | - SDD Mandates: List SEPA Direct Debit mandates, Get a SEPA Direct Debit mandate - SDD Subscriptions: List SEPA Direct Debit subscriptions, Get a SEPA Direct Debit subscription - SDD Collections: List SEPA Direct Debit collections, Get a SEPA Direct Debit collection |
sepa_direct_debit.write | Manage your SEPA Direct Debit payments View and manage your SEPA Direct Debit payments (when together with sepa_direct_debit.read) | - SDD Mandates: Create a SEPA Direct Debit mandate - SDD Subscriptions: Create a SEPA Direct Debit subscription |
terminal.read | View your payment terminals | - List terminals - Get a terminal payment |
terminal.write | Configure your terminals and initiate payments | - Create a terminal payment |
