Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qonto.com/llms.txt

Use this file to discover all available pages before exploring further.

If you want to build an integration that can access multiple Qonto organizations belonging to the same user, without asking for their consent separately for each one, you can use the User OAuth flow. This flow is a variant of the membership OAuth flow, but allows the user to grant consent to multiple organizations at once. The access_token obtained from this flow is then valid for all the organizations the user has consented to.
This flow is only available for applications that have been approved by Qonto. To be approved, you must be AIS/PIS compliant and have a clear use case for this flow. If you think your application could benefit from this flow, please open a support ticket from the Developer Portal. This flow is exclusive: if you use it, you cannot use the membership flow for the same application.

​
How does it work?

​
Step 1: User authentication

To obtain an access_token and a refresh_token for a user, follow the same OAuth flow as the membership flow with the following differences:
  1. Add the identity_type=user query parameter to the authorization URL.
  2. Request the user_organization.read scope in addition to the scopes you would normally request for the membership flow.
Then, redirect the user to the authorization URL. After the user grants their consent, you will receive an authorization_code that you can exchange for an access_token and a refresh_token as usual.

​
Step 2: Retrieve the list of organizations

Once you have an access_token for the user, retrieve the list of organizations the user has consented to by making a GET request to the /v2/user_organizations endpoint with the access_token in the Authorization header. This endpoint returns the list of organizations the user granted access to, along with their id, name, and membership_role.

​
Step 3: Access the organizations’ data

You can now call any other endpoint of the API with the same access_token. However, you must include the following header in your requests: X-Qonto-Organization-Id: {organization_id}. This header is required to specify which organization’s data you want to access, since the access_token is valid for multiple organizations.
If you provide an organization_id that the user has not consented to, you will receive a 403 Forbidden error. Same if you don’t provide the header.

​
Step 4: Modify the list of organizations

If you want to offer the user the possibility to modify the list of organizations they have consented to, you can redirect the user to the login flow as described in step 1. The user will then be able to modify their consent and grant access to new organizations or revoke access to existing ones. After the user modifies their consent, you can retrieve the updated list of organizations by calling the /v2/user_organizations endpoint again.