Need the authentication method or the OAuth scope required for an endpoint? Check the endpoints access table. Every endpoint page also shows it right below its method and URL.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 |
| Check the organization’s current subscription plan | subscription.read |
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 — Automate your business operations and Embed use cases 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 moreEndpoints access
Generated from the OpenAPIsecurity field of every published Business API operation. API key and OAuth 2.0 show which authentication methods the endpoint accepts; Scope(s) are the OAuth scopes the access token needs; a Sensitive tag marks endpoints that need a sensitive scope.
| Endpoint | API key | OAuth 2.0 | Scope(s) |
|---|---|---|---|
Retrieve an authorization codeGET /oauth2/auth | — | ||
Create or refresh tokensPOST /oauth2/token | — | ||
Revoke consentsDELETE /v2/oauth2/consents Sensitive | organization.read | ||
Retrieve SCA sessionGET /v2/sca_sessions/{sca-session-token} | — | ||
Retrieve mocked SCA sessionGET /v2/mocked_sca_sessions/{sca-session-token} | — | ||
Simulate user decisionPOST /v2/mocked_sca_sessions/{sca-session-token}/{decision} | — | ||
Retrieve the authenticated organization and list bank accountsGET /v2/organization Sensitive | organization.read | ||
Get user organizationsGET /v2/user_organizations | user_organization.read | ||
Show organization (v2 · deprecated) (deprecated)GET /v2/organizations/{slug} Sensitive | organization.read | ||
Show organization (v1 · deprecated) (deprecated)GET /v1/organizations/{slug} Sensitive | organization.read | ||
List business accountsGET /v2/bank_accounts Sensitive | organization.read | ||
Get a business accountGET /v2/bank_accounts/{id} Sensitive | organization.read | ||
Close a business accountPOST /v2/bank_accounts/{id}/close | bank_account.write | ||
Create a business accountPOST /v2/bank_accounts | bank_account.write | ||
Update a business accountPATCH /v2/bank_accounts/{id} | bank_account.write | ||
Download the IBAN certificateGET /v2/bank_accounts/{id}/iban_certificate Sensitive | organization.read | ||
List membershipsGET /v2/memberships Sensitive | organization.read | ||
Retrieve the authenticated membershipGET /v2/membership | membership.read | ||
Create a membershipPOST /v2/memberships/invite_employee_or_accountant | membership.write | ||
List teamsGET /v2/teams | team.read | ||
Create a teamPOST /v2/teams | team.write | ||
Update a teamPATCH /v2/teams/{id} | team.write | ||
List labelsGET /v2/labels Sensitive | organization.read | ||
Retrieve a labelGET /v2/labels/{id} Sensitive | organization.read | ||
Retrieve the organization’s current subscription planGET /v2/subscription | subscription.read | ||
List transactionsGET /v2/transactions Sensitive | organization.read | ||
Retrieve a transactionGET /v2/transactions/{id} Sensitive | organization.read | ||
List child transaction linksGET /v2/transactions/{id}/child_transaction_links Sensitive | organization.read | ||
List statementsGET /v2/statements Sensitive | organization.read | ||
Retrieve a statementGET /v2/statements/{id} Sensitive | organization.read | ||
Retrieve an attachmentGET /v2/attachments/{id} Sensitive | organization.read | ||
Upload an attachmentPOST /v2/attachments | attachment.write | ||
List attachments for a transactionGET /v2/transactions/{id}/attachments Sensitive | organization.read | ||
Upload an attachment to a transactionPOST /v2/transactions/{id}/attachments | attachment.write | ||
Remove an attachment from a transactionDELETE /v2/transactions/{transaction_id}/attachments/{attachment_id} | attachment.write | ||
Remove all attachments from a transactionDELETE /v2/transactions/{id}/attachments | attachment.write | ||
List SEPA transfersGET /v2/sepa/transfers Sensitive | organization.read | ||
Get SEPA transferGET /v2/sepa/transfers/{id} Sensitive | organization.read | ||
Create a SEPA transferPOST /v2/sepa/transfers Sensitive | payment.write | ||
Download proof of a SEPA transferPOST /v2/sepa/transfers/{id}/download_proof Sensitive | payment.write | ||
Cancel SEPA transferPOST /v2/sepa/transfers/{id}/cancel Sensitive | payment.write | ||
List SEPA beneficiariesGET /v2/sepa/beneficiaries Sensitive | organization.read | ||
Retrieve a SEPA beneficiaryGET /v2/sepa/beneficiaries/{id} Sensitive | organization.read | ||
Add a SEPA beneficiaryPOST /v2/sepa/beneficiaries Sensitive | payment.write | ||
Update a SEPA beneficiaryPATCH /v2/sepa/beneficiaries/{id} Sensitive | payment.write | ||
Delete a SEPA beneficiaryDELETE /v2/sepa/beneficiaries/{id} Sensitive | payment.write | ||
Trust SEPA beneficiariesPATCH /v2/sepa/beneficiaries/trust Sensitive | beneficiary.trust | ||
Untrust SEPA beneficiariesPATCH /v2/sepa/beneficiaries/untrust Sensitive | payment.write | ||
Verify a SEPA payeePOST /v2/sepa/verify_payee Sensitive | payment.write | ||
Bulk verify SEPA payeesPOST /v2/sepa/bulk_verify_payee Sensitive | payment.write | ||
List Bulk TransfersGET /v2/sepa/bulk_transfers Sensitive | organization.read | ||
Get Bulk TransferGET /v2/sepa/bulk_transfers/{id} Sensitive | organization.read | ||
Create a Bulk TransferPOST /v2/sepa/bulk_transfers Sensitive | payment.write | ||
List SEPA recurring transfersGET /v2/sepa/recurring_transfers Sensitive | organization.read | ||
Get SEPA recurring transferGET /v2/sepa/recurring_transfers/{id} Sensitive | organization.read | ||
Create a SEPA recurring transferPOST /v2/sepa/recurring_transfers Sensitive | payment.write | ||
Cancel SEPA recurring transferPOST /v2/sepa/recurring_transfers/{id}/cancel Sensitive | payment.write | ||
Create an internal transferPOST /v2/internal_transfers Sensitive | internal_transfer.write | ||
Check if the organization is eligible for international transfersGET /v2/international/eligibility Sensitive | organization.read | ||
Get available currencies for international transfersGET /v2/international/currencies Sensitive | organization.read | ||
Create a new international transfer quotePOST /v2/international/quotes Sensitive | international_transfer.write | ||
List international beneficiariesGET /v2/international/beneficiaries Sensitive | organization.read | ||
List requirements for an international beneficiaryPOST /v2/international/beneficiaries/requirements Sensitive | international_transfer.write | ||
Create an international beneficiaryPOST /v2/international/beneficiaries Sensitive | international_transfer.write | ||
Update an international beneficiaryPUT /v2/international/beneficiaries/{id} Sensitive | international_transfer.write | ||
Delete an international beneficiaryDELETE /v2/international/beneficiaries/{id} Sensitive | international_transfer.write | ||
List international transfer requirementsPOST /v2/international/transfers/requirements Sensitive | international_transfer.write | ||
Create an international transferPOST /v2/international/transfers Sensitive | international_transfer.write | ||
List payment linksGET /v2/payment_links | payment_link.read | ||
Get a payment linkGET /v2/payment_links/{id} | payment_link.read | ||
Create a payment linkPOST /v2/payment_links | payment_link.write | ||
Deactivate a payment linkPATCH /v2/payment_links/{id}/deactivate | payment_link.write | ||
List payments for a payment linkGET /v2/payment_links/{id}/payments | payment_link.read | ||
List available payment methodsGET /v2/payment_links/payment_methods | payment_link.read | ||
Connect to the payment links providerPOST /v2/payment_links/connections | payment_link.write | ||
Get the connection statusGET /v2/payment_links/connections | payment_link.read | ||
List terminalsGET /v2/terminals | terminal.read | ||
Create a terminal paymentPOST /v2/terminals/{id}/payment | terminal.write | ||
Get a terminal paymentGET /v2/terminal_payments/{id} | terminal.read | ||
List SEPA Direct Debit mandatesGET /v2/sepa/direct_debit_mandates | sepa_direct_debit.read | ||
Get a SEPA Direct Debit mandateGET /v2/sepa/direct_debit_mandates/{direct_debit_mandate_id} | sepa_direct_debit.read | ||
Create a SEPA Direct Debit mandatePOST /v2/sepa/direct_debit_mandates | sepa_direct_debit.write | ||
Cancel a SEPA Direct Debit mandatePOST /v2/sepa/direct_debit_mandates/{direct_debit_mandate_id}/cancel | sepa_direct_debit.write | ||
List SEPA Direct Debit subscriptionsGET /v2/sepa/direct_debit_subscriptions | sepa_direct_debit.read | ||
Get a SEPA Direct Debit subscriptionGET /v2/sepa/direct_debit_subscriptions/{direct_debit_subscription_id} | sepa_direct_debit.read | ||
Create a SEPA Direct Debit subscriptionPOST /v2/sepa/direct_debit_subscriptions | sepa_direct_debit.write | ||
List SEPA Direct Debit collectionsGET /v2/sepa/direct_debit_collections | sepa_direct_debit.read | ||
Get a SEPA Direct Debit collectionGET /v2/sepa/direct_debit_collections/{direct_debit_collection_id} | sepa_direct_debit.read | ||
List cardsGET /v2/cards | card.read | ||
List card appearancesGET /v2/cards/appearances | card.read | ||
Retrieve a card iframe urlGET /v2/cards/{id}/data_view | card.read | ||
Create a cardPOST /v2/cards | card.write | ||
Bulk create cardsPOST /v2/cards_bulk | card.write | ||
Update a card’s limitsPATCH /v2/cards/{id}/limits | card.write | ||
Update a card’s nicknamePATCH /v2/cards/{id}/nickname | card.write | ||
Update a card’s optionsPATCH /v2/cards/{id}/options | card.write | ||
Update a card’s restrictionsPATCH /v2/cards/{id}/restrictions | card.write | ||
Lock a cardPUT /v2/cards/{id}/lock | card.write | ||
Unlock a cardPUT /v2/cards/{id}/unlock | card.write | ||
Report a physical card as lostPUT /v2/cards/{id}/lost | card.write | ||
Report a physical card as stolenPUT /v2/cards/{id}/stolen | card.write | ||
Discard a cardPUT /v2/cards/{id}/discard | card.write | ||
List clientsGET /v2/clients | client.read | ||
Retrieve a clientGET /v2/clients/{id} | client.read | ||
Create a clientPOST /v2/clients | client.write | ||
Update a clientPATCH /v2/clients/{id} | client.write | ||
Delete a clientDELETE /v2/clients/{id} | client.write | ||
List productsGET /v2/products | product.read | ||
Retrieve a productGET /v2/products/{id} | product.read | ||
Create a productPOST /v2/products | product.write | ||
Delete a productDELETE /v2/products/{id} | product.write | ||
List client invoicesGET /v2/client_invoices | client_invoices.read | ||
Retrieve a client invoiceGET /v2/client_invoices/{id} | client_invoices.read | ||
Create a client invoicePOST /v2/client_invoices | client_invoice.write | ||
Update a draft client invoicePATCH /v2/client_invoices/{id} | client_invoice.write | ||
Delete a client invoiceDELETE /v2/client_invoices/{id} | client_invoice.write | ||
Finalize a client invoicePOST /v2/client_invoices/{id}/finalize | client_invoice.write | ||
Send a client invoice via emailPOST /v2/client_invoices/{id}/send | client_invoice.write | ||
Send a client invoice via e-invoicePOST /v2/client_invoices/{id}/send_by_einvoice | client_invoice.write | ||
Mark a client invoice as paidPOST /v2/client_invoices/{id}/mark_as_paid | client_invoice.write | ||
Unmark a client invoice as paidPOST /v2/client_invoices/{id}/unmark_as_paid | client_invoice.write | ||
Cancel a client invoicePOST /v2/client_invoices/{id}/mark_as_canceled | client_invoice.write | ||
Import client invoices in bulkPOST /v2/client_invoices/bulk | client_invoice.write | ||
Create a client invoice uploadPOST /v2/client_invoices/uploads | client_invoice.write | ||
Retrieve a client invoice uploadGET /v2/client_invoices/uploads/{id} | client_invoices.read | ||
List quotesGET /v2/quotes | client_invoices.read | ||
Retrieve a quoteGET /v2/quotes/{id} | client_invoices.read | ||
Create a quotePOST /v2/quotes | client_invoice.write | ||
Update a quotePATCH /v2/quotes/{id} | client_invoice.write | ||
Delete a quoteDELETE /v2/quotes/{id} | client_invoice.write | ||
Send a quote via emailPOST /v2/quotes/{id}/send | client_invoice.write | ||
List credit notesGET /v2/credit_notes | client_invoices.read | ||
Retrieve a credit noteGET /v2/credit_notes/{id} | client_invoices.read | ||
Create a credit notePOST /v2/credit_notes | client_invoice.write | ||
Download a credit noteGET /v2/credit_notes/{credit_note_id}/file | client_invoices.read | ||
List recurring invoicesGET /v2/recurring_invoices | client_invoices.read | ||
Retrieve a recurring invoiceGET /v2/recurring_invoices/{id} | client_invoices.read | ||
Create a recurring invoicePOST /v2/recurring_invoices | client_invoice.write | ||
Update a recurring invoicePUT /v2/recurring_invoices/{id} | client_invoice.write | ||
Cancel a recurring invoicePOST /v2/recurring_invoices/{id}/cancel | client_invoice.write | ||
Reactivate a recurring invoicePOST /v2/recurring_invoices/{id}/reactivate | client_invoice.write | ||
Suspend a recurring invoicePOST /v2/recurring_invoices/{id}/suspend | client_invoice.write | ||
Validate a recurring invoicePOST /v2/recurring_invoices/validate | client_invoice.write | ||
List payment reminder configurationsGET /v2/reminders | client_invoices.read | ||
Get a payment reminder configurationGET /v2/reminders/{id} | client_invoices.read | ||
Configure payment reminders for a clientPOST /v2/reminders | client_invoice.write | ||
Replace a payment reminder configurationPUT /v2/reminders/{id} | client_invoice.write | ||
Delete a payment reminder configurationDELETE /v2/reminders/{id} | client_invoice.write | ||
Get invoicing settingsGET /v2/settings | client_invoices.read | ||
Update invoicing settingsPUT /v2/settings | client_invoice.write | ||
Get e-invoicing settingsGET /v2/einvoicing/settings | einvoicing.read | ||
Search suppliersPOST /v2/suppliers/search | supplier_invoice.read | ||
Retrieve a supplierGET /v2/suppliers/{id} | supplier_invoice.read | ||
Create a supplierPOST /v2/suppliers | supplier_invoice.write | ||
Update a supplierPUT /v2/suppliers/{id} | supplier_invoice.write | ||
List supplier invoicesGET /v2/supplier_invoices | supplier_invoice.read | ||
Retrieve a supplier invoiceGET /v2/supplier_invoices/{id} | supplier_invoice.read | ||
Create supplier invoicesPOST /v2/supplier_invoices/bulk | supplier_invoice.write | ||
Mark a supplier invoice as paidPOST /v2/supplier_invoices/{id}/mark_as_paid | supplier_invoice.write | ||
Reject a supplier invoicePOST /v2/supplier_invoices/{id}/reject | supplier_invoice.write | ||
Unmark a supplier invoice as paidPOST /v2/supplier_invoices/{id}/unmark_as_paid | supplier_invoice.write | ||
List requestsGET /v2/requests Sensitive | organization.read | ||
Create transfer requestPOST /v2/requests/transfers | request_transfers.write | ||
Create multi transfer requestPOST /v2/requests/multi_transfers | request_transfers.write | ||
Create a flash card requestPOST /v2/requests/flash_cards | none declared | ||
Create a virtual card requestPOST /v2/requests/virtual_cards | none declared | ||
Approve a requestPOST /v2/requests/{request_type}/{id}/approve | request_review.write | ||
Decline a requestPOST /v2/requests/{request_type}/{id}/decline | request_review.write | ||
Retrieve an insurance contractGET /v2/insurance_contracts/{id} | insurance_contract.read | ||
Create an insurance contractPOST /v2/insurance_contracts | insurance_contract.write | ||
Update an insurance contractPATCH /v2/insurance_contracts/{id} | insurance_contract.write | ||
Upload a document to an insurance contractPOST /v2/insurance_contracts/{id}/attachments | insurance_contract.write | ||
Remove a document from an insurance contractDELETE /v2/insurance_contracts/{id}/attachments/{attachment_id} | insurance_contract.write | ||
List cash flow categoriesGET /v2/cash_flow_categories | cash_flow_category.read | ||
Create a cash flow categoryPOST /v2/cash_flow_categories | cash_flow_category.write | ||
Update a cash flow categoryPATCH /v2/cash_flow_categories/{id} | cash_flow_category.write | ||
Delete a cash flow categoryDELETE /v2/cash_flow_categories/{id} | cash_flow_category.write | ||
Assign a cash flow category to transactionsPOST /v2/cash_flow_categories/assignments | cash_flow_category.write | ||
Create a cash flow subcategoryPOST /v2/cash_flow_categories/{category_id}/subcategories | cash_flow_category.write | ||
Unassign a cash flow category from transactionsPOST /v2/cash_flow_categories/unassignments | cash_flow_category.write | ||
List cash flow scenariosGET /v2/cash_flow_scenarios | cash_flow_category.read | ||
Create a cash flow scenarioPOST /v2/cash_flow_scenarios | cash_flow_category.write | ||
Update a cash flow scenarioPATCH /v2/cash_flow_scenarios/{id} | cash_flow_category.write | ||
Delete a cash flow scenarioDELETE /v2/cash_flow_scenarios/{id} | cash_flow_category.write | ||
List cash flow targetsGET /v2/cash_flow_targets | cash_flow_category.read | ||
Create or update cash flow targetsPUT /v2/cash_flow_targets | cash_flow_category.write | ||
Delete a cash flow targetDELETE /v2/cash_flow_targets | cash_flow_category.write | ||
List webhook subscriptionsGET /v2/webhook_subscriptions | webhook | ||
Get a webhook subscriptionGET /v2/webhook_subscriptions/{id} | webhook | ||
Create a new webhook subscriptionPOST /v2/webhook_subscriptions | webhook | ||
Update a webhook subscriptionPUT /v2/webhook_subscriptions/{id} | webhook | ||
Delete a webhook subscriptionDELETE /v2/webhook_subscriptions/{id} | webhook | ||
Dispatch an encoded requestPOST /v1/encoded_requests/dispatch | none declared | ||
Create an Embed Auth LinkPOST /v1/embed_auth_links | embed_auth_link.write |
Endpoints requiring Strong Customer Authentication
The following endpoints were marked as requiring Strong Customer Authentication (SCA) in the former endpoints access table. Endpoint pages also describe their SCA requirements below the method and URL.- Trust SEPA beneficiaries
- Create an international transfer
- Approve a request
- Create a card
- Bulk create cards
- Unlock a card
- Update a card’s limits
- Close a business account
Available scopes
Generated fromapi-reference/business-api/components/security/schemes.yml (scope descriptions and the x-sensitive-scopes list).
Consent messages
Consent messages are displayed to Qonto users on the consent screen during the OAuth authorization flow. Scopes marked NA do not display a permission entry on the consent screen.| Scope | Consent message | Restrictions |
|---|---|---|
organization.read | Get and export info about your balance, IBAN, transactions, organization and team | |
payment.write | 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) | |
internal_transfer.write | NA | |
international_transfer.write | Make international transfers | |
attachment.read | Get and export attachments | |
attachment.write | Upload attachments Remove attachments from transactions | |
membership.read | Get and export your personal data, e.g. identity information, contact details (including your address), and role | |
membership.write | Invite new members to teams | |
supplier_invoice.read | Get the list of supplier invoices | |
supplier_invoice.write | Generate 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_invoice.write | Create and update client invoices, quotes and add clients | |
product.read | Get the list of products | |
product.write | Create products | |
client.read | Get all the details about clients | |
client.write | Create, update and delete clients | |
team.read | Get the list of teams | |
team.write | NA | |
card.read | Get all the details about your cards | |
card.write | Create new cards | |
insurance_contract.read | Share your insurance policy details with Qonto | |
insurance_contract.write | Sync your insurance policy details with Qonto | |
request_review.write | NA | |
request_transfers.write | NA | |
request_cards.write | NA | |
bank_account.write | NA | |
beneficiary.trust | Mark beneficiaries as trusted or remove them from trusted beneficiaries | Automate your business operations and Embed use cases only |
payment_link.write | Create and manage payment links | |
payment_link.read | View payment links and payment activity | |
einvoicing.read | Get e-invoicing settings | |
user_organization.read | View the organizations the user grant access to | |
cash_flow_category.read | View your cash flow categories | |
cash_flow_category.write | Create cash flow categories and assign them to transactions | |
subscription.read | View your organization’s current subscription plan | |
webhook | NA | |
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) | |
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) | |
terminal.read | View your payment terminals | |
terminal.write | Configure your terminals and initiate payments |
