> ## 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.
# Retrieve an authorization code
> Retrieves the authorization of the Qonto user i.e. an authorization code that you will be able to exchange for a [set of tokens](/api-reference/business-api/authentication/oauth2/create_tokens).
1. Your app should include a "Connect with Qonto" button which should trigger this endpoint;
If you are triggering this endpoint on the Sandbox environment (https://oauth-sandbox.staging.qonto.co), please make sure to be logged in on the [Sandbox web-app](https://sandbox.staging.qonto.co/devportal) first through your [Developer Portal](https://developers.qonto.com/) account.
If you just want to connect your app to one single organization, you can just send the endpoint URL to the Qonto user from whom you need to get the consent.
2. After clicking on your button, the Qonto user will be redirected to Qonto and will have to authenticate;
3. (optional) The Qonto will have to select an organization;
3. The Qonto user will have to give their consent to your app for the organization they have just selected (or for the organization identified by the `organization_id` or the `registration_id` query parameter);
4. The Qonto user will be automatically redirected back to your `redirect_uri`.
## OpenAPI
````yaml get /oauth2/auth
openapi: 3.1.1
info:
version: v2
title: Qonto
servers:
- url: https://thirdparty.qonto.com
description: Production URL
- url: https://thirdparty-sandbox.staging.qonto.co
description: Sandbox URL
security:
- OAuth:
- organization.read
- membership.read
- membership.write
- attachment.write
- internal_transfer.write
- payment.write
- supplier_invoice.write
- supplier_invoice.read
- client_invoices.read
- client_invoice.write
- client.read
- client.write
- product.read
- product.write
- request_review.write
- request_review.read
- team.read
- team.write
- request_transfers.write
- insurance_contract.read
- insurance_contract.write
- card.read
- card.write
- bank_account.write
- beneficiary.trust
- webhook
- payment_link.write
- payment_link.read
- sepa_direct_debit.read
- sepa_direct_debit.write
- terminal.read
- terminal.write
- SecretKey: []
paths:
/oauth2/auth:
servers:
- url: https://oauth.qonto.com
description: Production URL
- url: https://oauth-sandbox.staging.qonto.co
description: Sandbox URL
get:
tags:
- OAuth 2.0
summary: Retrieve an authorization code
description: >-
Retrieves the authorization of the Qonto user i.e. an authorization code
that you will be able to exchange for a [set of
tokens](/api-reference/business-api/authentication/oauth2/create_tokens).
1. Your app should include a "Connect with Qonto" button which should
trigger this endpoint;
If you are triggering this endpoint on the Sandbox environment (https://oauth-sandbox.staging.qonto.co), please make sure to be logged in on the [Sandbox web-app](https://sandbox.staging.qonto.co/devportal) first through your [Developer Portal](https://developers.qonto.com/) account.
If you just want to connect your app to one single organization, you can just send the endpoint URL to the Qonto user from whom you need to get the consent.
2. After clicking on your button, the Qonto user will be redirected to
Qonto and will have to authenticate;
3. (optional) The Qonto will have to select an organization;
3. The Qonto user will have to give their consent to your app for the
organization they have just selected (or for the organization identified
by the `organization_id` or the `registration_id` query parameter);
4. The Qonto user will be automatically redirected back to your
`redirect_uri`.
parameters:
- name: client_id
in: query
required: true
example: 475670cc-e41a-4baa-8eb6-4329af7d1450
schema:
type: string
description: >-
Unique identifier of your application. Please sign up to the
[Developer Portal](https://developers.qonto.com/sign-up/) to get
one.
Example: "475670cc-e41a-4baa-8eb6-4329af7d1450"
- name: redirect_uri
in: query
required: true
example: https%3A%2F%2Fmy-company-server.com%2F
schema:
type: string
description: >-
URI to which the Qonto user will be redirected back after they have
accepted the connection of your application with their account.
**☝️ `redirect_uri` needs to be encoded through [this
tool](https://www.urlencoder.org/).**
Example: "https%3A%2F%2Fmy-company-server.com%2F"
- name: scope
in: query
required: true
example: offline_access organization.read
schema:
type: string
description: >-
It represents the list of permission that your application is
requesting on the user account. It can be a single scope or a list
of scopes together. In the latter case, the scopes must be written
as a space separated list of values.
Examples:
- Single scope : "offline_access"
- Multiple scopes: "offline_access organization.read payment.write"
Use the `offline_access` scope if you require a refresh token.
Please refer to the API Reference section of this documentation to
find which specific scopes are required for the actions you would
like to perform. You will find the list of the available scopes
[here](/get-started/business-api/authentication/oauth/available-scopes).
- name: response_type
in: query
required: true
example: code
schema:
type: string
description: Type of authentication flow. Only `code` is supported.
- name: state
in: query
required: true
example: this-is-my-unique-value
schema:
type: string
description: >-
It is a security parameter to protect against forgery attacks.
You need to pass a value that is unique to the user authenticating.
At the end of the authentication process, you should compare the
received state with the one you provided to make sure they are
equal.
Example: "this-is-my-unique-value"
- name: organization_id
in: query
required: false
example: 1acf250c-a068-47fa-ae9d-032b85c148dc
schema:
type: string
description: >-
If you want to restrict the user to connect to a specific
organization, you can pass the `organization_id` here. If this
parameter is present, then the user won't be asked to select an
organization during the OAuth flow.
Example: "1acf250c-a068-47fa-ae9d-032b85c148dc"
- name: registration_id
in: query
required: false
example: a584b060-8c96-488d-8bbb-74f0d3d2803c
schema:
type: string
description: >-
Starts the OAuth flow with a pre-selected organization, linked to
the `registration_id` obtained during the onboarding flow. If this
parameter is provided, then the user won't be asked to select an
organization during the OAuth flow.
Example: "a584b060-8c96-488d-8bbb-74f0d3d2803c"
responses:
'302':
description: >-
Redirects the user to Qonto in order to get their authorization.
⚠️ Once the user is redirected to your redirect URI, you need to
check the received `state` parameter against the one you provided on
the request. If they do not match, you should stop the process as
the request might have been forged by a malicious third party.
headers:
Location:
description: Redirect URI with authorization code
schema:
type: string
example: >-
https://my-company-server.com?code=ory_ac_lY8t9YfHv3N2tLEKFfgL5_XADs2sbcxVGcYPbneMAAo.w-9CyjAz0DB-_3q2s5ZpYk-oFEUCBcMTU_s5iy07CA0&scope=offline_access+organization.read&state=this-is-my-unique-value
'400':
description: Returns a bad request error.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: OAuth2 error code
example: invalid_grant
error_verbose:
type: string
description: Detailed error description
example: >-
The provided authorization grant (e.g., authorization
code, resource owner credentials) or refresh token is
invalid, expired, revoked, does not match the redirection
URI used in the authorization request, or was issued to
another client
error_description:
type: string
description: Human-readable error description
example: >-
The provided authorization grant (e.g., authorization
code, resource owner credentials) or refresh token is
invalid, expired, revoked, does not match the redirection
URI used in the authorization request, or was issued to
another client
status_code:
type: integer
description: HTTP status code
example: 400
required:
- error
- error_verbose
- error_description
- status_code
examples:
invalid_grant:
summary: Invalid Grant Error
value:
error: invalid_grant
error_verbose: >-
The provided authorization grant (e.g., authorization
code, resource owner credentials) or refresh token is
invalid, expired, revoked, does not match the redirection
URI used in the authorization request, or was issued to
another client
error_description: >-
The provided authorization grant (e.g., authorization
code, resource owner credentials) or refresh token is
invalid, expired, revoked, does not match the redirection
URI used in the authorization request, or was issued to
another client
status_code: 400
'404':
description: >-
Returns a not found error. This is generally due to a wrong
`client_id`.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: not_found
error_description:
type: string
example: Client not found
'500':
description: Returns an internal server.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: internal_server_error
error_description:
type: string
example: Internal Server Error
required:
- error
- error_description
security:
- {}
components:
securitySchemes:
OAuth:
type: oauth2
description: >
Bearer authorization header: `Bearer `, where `` is the
access token received from the authorization server at the end of the
[OAuth 2.0
flow](/get-started/business-api/authentication/oauth/oauth-flow).
flows:
authorizationCode:
refreshUrl: https://oauth.qonto.com/oauth2/token
authorizationUrl: https://oauth.qonto.com/oauth2/auth
scopes:
attachment.read: Retrieve attachments
attachment.write: Upload attachments and remove attachments from transactions
bank_account.write: Create, update and close bank accounts
beneficiary.trust: Trust SEPA beneficiaries
card.read: Retrieve cards
card.write: Create or update cards
client.read: Retrieve clients
client.write: Create clients
client_invoice.write: Create client invoices
client_invoices.read: Retrieve client invoices and credit notes
einvoicing.read: Retrieve e-invoicing settings
embed_auth_link.write: Create Embed auth links
insurance_contract.read: Retrieve insurance contracts
insurance_contract.write: Create and update insurance contracts
internal_transfer.write: >-
Create internal transfers (between 2 Qonto accounts of the same
organization)
international_transfer.write: Create international transfers
membership.read: Retrieve the authentified membership
membership.write: Invite team members
offline_access: Retrieve a refresh token
organization.read: >-
Retrieve organization, bank accounts, transactions, transfers,
beneficiaries, labels, memberships, requests & statements
payment.write: Create external transfers and untrust beneficiaries
payment_link.read: >-
Retrieve payment links, their payments, and the available payment
methods
payment_link.write: >-
Connect to the payment links provider, create and deactivate
payment links
product.read: Retrieve products
product.write: Create products
request_cards.write: Create card requests
request_review.write: Approve or decline requests
request_transfers.write: Create transfer requests
sepa_direct_debit.read: View SEPA Direct Debit payments
sepa_direct_debit.write: Manage SEPA Direct Debit payments
supplier_invoice.read: Retrieve supplier invoices
supplier_invoice.write: Create supplier invoices
team.read: Retrieve teams
team.write: Create teams
terminal.read: View your payment terminals
terminal.write: Configure your terminals and initiate payments
webhook: >-
Receive a notification each time a particular event occurs in
Qonto
tokenUrl: https://oauth.qonto.com/oauth2/token
SecretKey:
type: apiKey
description: cf. [API key](/get-started/business-api/authentication/api-key)
name: Authorization
in: header
````