Create or refresh tokens

curl --request POST \
  --url https://thirdparty.qonto.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=475670cc-e41a-4baa-8eb6-4329af7d1450 \
  --data client_secret=this-is-my-amazing-secret \
  --data grant_type=authorization_code \
  --data redirect_uri=https://my-company-server.com \
  --data code=ory_ac_lY8t9YfHv3N2tLEKFfgL5_XADs2sbcxVGcYPbneMAAo.w-9CyjAz0DB-_3q2s5ZpYk-oFEUCBcMTU_s5iy07CA0 \
  --data refresh_token=ory_rt_7kRxfEQzaBuL9RRSusC_vKRUNmtr1jdUC_i2NORdmZU.Ze-WLB5gZa7UIbhHSgv3KCpqvJHMZHUn6hgc1XOGoRU

{
  "access_token": "ory_at_2-ocNFHnqdPjEOs9FdHMf6jKO4VNTVvLp3zChWVItoY.CaKVRy-plm-pr2mKk22Nt3ThgVjHmfkrolgTmMapvCI",
  "expires_in": 3600,
  "scope": "offline_access organization.read",
  "token_type": "bearer",
  "refresh_token": "ory_rt_7kRxfEQzaBuL9RRSusC_vKRUNmtr1jdUC_i2NORdmZU.Ze-WLB5gZa7UIbhHSgv3KCpqvJHMZHUn6hgc1XOGoRU",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InByaXZhdGU6NzY4ZTk0OTYtMmJlOS00OTg4LTllNzUtZTU2NTEwODI5YzhjIiwidHlwIjoiSldUIn0.eyJhdF9oYXNoIjoiYVJUdFZBbndFX0RDblhSa1hhMnhxQSIsImF1ZCI6WyJsb2NhbGhvc3QtdGVzdC1jbGllbnQtYXBwIl0sImF1dGhfdGltZSI6MTc2MDAyMDQzMSwiZW1haWwiOiJvd25lckBxb250by5ldSIsImV4cCI6MTc2MDAyNDA4MywiaWF0IjoxNzYwMDIwNDgzLCJpc3MiOiJodHRwczovL29hdXRoLXNhbmRib3guc3RhZ2luZy5xb250by5jbyIsImp0aSI6IjBlYjQ3YjczLTI1NzgtNDQ3NC05MjNhLWQ3ZmQ4NTQ1NzJiYyIsInJhdCI6MTc2MDAyMDM1Mywic2lkIjoiZmYxYTY0MjgtOTdkZi00Yzc4LWJjOTgtM2JjMjVlNjM1MmQwIiwic3ViIjoiMDE5NjVkYzQtZmMxZi03ODc0LTgzYjQtYjU1MjhiZWEwYThkIn0.N2M3LiDbNvA115Foed1YVJ8mqr_mq_8-gmAJ6FkhWyx45gpUpeKji4U0lWbh3sYN1cd90aSwhZnrxxTxVsJAo6pvbWkw0ghzMasmltqAbxttPW-GgfieUh1ipbgE7ekmNPT6Op_qAU_E5OhZDKd01HC07on5FdVkdHeZGSN0ahZ4MezlmYA85Ig_qDM-7hW0DQhlATRuYpatl5hIE_7oiGsTrcsUgNYxoIILOCSP_FhHGJRtKah1wVqRhPu5fQG277mOTugI463yMDzAJMRgptEfpA02whnB6tycXKNfRDdFbYS1jxKzwSFTX3QAmhDWWJl4fgyAYe3ur_pD9jqlb9hpZwXFThJzfxyvKkPwiZjaVmWZi1dAhAzE2jZH6ktwimVbDjI3uWiOwz10AsYoTpZXf17jJRrR7bzj_ayYlh1G3JfIEPgiK4QkekWcV9uerWS_9ziyPqVOZw-sBEGZC19JcvMW1pzlK9az9aTKekBmzmCdXw9ankc_-1rfd9rB2oco_-_Vh9hKk5jHExHk0GZ1C48C-UZd7iB0VpQC7R_93gvHk3crIvyPqcZQl7PPBoqYK9thuliLpCkPhJ_nYX-2RDUfeI6wHL26hklCU3t-N-SAecZ34WBkk9S30cvY333HPZi1lNxEptc0obmjCMCYcSg0Sr_Ctk9Z8nXrMEU"
}

OAuth 2.0

Create or refresh tokens

This call must be performed on your backend as you should never expose your client secret.

Creates or refreshes a set of tokens for the authenticated membership.

This set of tokens contains:

always: an access token (you will need this token to authenticate yourself to any other endpoint);
if you used the offline_access scope when retrieving an authorization code: a refresh token;
if you used the openid scope when retrieving an authorization code: an ID token.

The access token and the ID token are valid for 1 hour, the refresh token for 90 days. Once the access token has reached its expiration date, you won’t be able to access the Business API with it anymore.

If you create a set of tokens for the first time

Use the authorization code you’ve received at the previous step.

If you want to refresh an existing access token

Use the last refresh token you’ve received.

Don’t forget to store your new refresh token as the previous one will be invalidated 👉 you will need it for the next refresh.

Always opt for a proactive refresh vs a reactive refresh to avoid reaching the rate limitations, i.e. check if your access token is expired and refresh it if needed before making any API call instead of refreshing it after getting a 401 error.

POST

oauth2

token

Create or refresh tokens

curl --request POST \
  --url https://thirdparty.qonto.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=475670cc-e41a-4baa-8eb6-4329af7d1450 \
  --data client_secret=this-is-my-amazing-secret \
  --data grant_type=authorization_code \
  --data redirect_uri=https://my-company-server.com \
  --data code=ory_ac_lY8t9YfHv3N2tLEKFfgL5_XADs2sbcxVGcYPbneMAAo.w-9CyjAz0DB-_3q2s5ZpYk-oFEUCBcMTU_s5iy07CA0 \
  --data refresh_token=ory_rt_7kRxfEQzaBuL9RRSusC_vKRUNmtr1jdUC_i2NORdmZU.Ze-WLB5gZa7UIbhHSgv3KCpqvJHMZHUn6hgc1XOGoRU

{
  "access_token": "ory_at_2-ocNFHnqdPjEOs9FdHMf6jKO4VNTVvLp3zChWVItoY.CaKVRy-plm-pr2mKk22Nt3ThgVjHmfkrolgTmMapvCI",
  "expires_in": 3600,
  "scope": "offline_access organization.read",
  "token_type": "bearer",
  "refresh_token": "ory_rt_7kRxfEQzaBuL9RRSusC_vKRUNmtr1jdUC_i2NORdmZU.Ze-WLB5gZa7UIbhHSgv3KCpqvJHMZHUn6hgc1XOGoRU",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InByaXZhdGU6NzY4ZTk0OTYtMmJlOS00OTg4LTllNzUtZTU2NTEwODI5YzhjIiwidHlwIjoiSldUIn0.eyJhdF9oYXNoIjoiYVJUdFZBbndFX0RDblhSa1hhMnhxQSIsImF1ZCI6WyJsb2NhbGhvc3QtdGVzdC1jbGllbnQtYXBwIl0sImF1dGhfdGltZSI6MTc2MDAyMDQzMSwiZW1haWwiOiJvd25lckBxb250by5ldSIsImV4cCI6MTc2MDAyNDA4MywiaWF0IjoxNzYwMDIwNDgzLCJpc3MiOiJodHRwczovL29hdXRoLXNhbmRib3guc3RhZ2luZy5xb250by5jbyIsImp0aSI6IjBlYjQ3YjczLTI1NzgtNDQ3NC05MjNhLWQ3ZmQ4NTQ1NzJiYyIsInJhdCI6MTc2MDAyMDM1Mywic2lkIjoiZmYxYTY0MjgtOTdkZi00Yzc4LWJjOTgtM2JjMjVlNjM1MmQwIiwic3ViIjoiMDE5NjVkYzQtZmMxZi03ODc0LTgzYjQtYjU1MjhiZWEwYThkIn0.N2M3LiDbNvA115Foed1YVJ8mqr_mq_8-gmAJ6FkhWyx45gpUpeKji4U0lWbh3sYN1cd90aSwhZnrxxTxVsJAo6pvbWkw0ghzMasmltqAbxttPW-GgfieUh1ipbgE7ekmNPT6Op_qAU_E5OhZDKd01HC07on5FdVkdHeZGSN0ahZ4MezlmYA85Ig_qDM-7hW0DQhlATRuYpatl5hIE_7oiGsTrcsUgNYxoIILOCSP_FhHGJRtKah1wVqRhPu5fQG277mOTugI463yMDzAJMRgptEfpA02whnB6tycXKNfRDdFbYS1jxKzwSFTX3QAmhDWWJl4fgyAYe3ur_pD9jqlb9hpZwXFThJzfxyvKkPwiZjaVmWZi1dAhAzE2jZH6ktwimVbDjI3uWiOwz10AsYoTpZXf17jJRrR7bzj_ayYlh1G3JfIEPgiK4QkekWcV9uerWS_9ziyPqVOZw-sBEGZC19JcvMW1pzlK9az9aTKekBmzmCdXw9ankc_-1rfd9rB2oco_-_Vh9hKk5jHExHk0GZ1C48C-UZd7iB0VpQC7R_93gvHk3crIvyPqcZQl7PPBoqYK9thuliLpCkPhJ_nYX-2RDUfeI6wHL26hklCU3t-N-SAecZ34WBkk9S30cvY333HPZi1lNxEptc0obmjCMCYcSg0Sr_Ctk9Z8nXrMEU"
}

Headers

X-Qonto-Staging-Token

string

Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.

Body

application/x-www-form-urlencoded

client_id

string

required

Unique identifier of your application. Please sign up to the Developer Portal to get one.

Example:

"475670cc-e41a-4baa-8eb6-4329af7d1450"

client_secret

string

required

Secret of your application. Please sign up to the Developer Portal to get one.

Example:

"this-is-my-amazing-secret"

grant_type

string

required

Type of token you are providing to generate your access token.

If you are creating your first set of tokens: authorization_code
If you are refreshing an existing access token: refresh_token

Example:

"authorization_code"

redirect_uri

string

URI to which the Qonto user will be redirected back after they have accepted the connection of your application with their account. This value is used here for verification purpose in case you provided multiple redirect_uri. Use this parameter when creating your first set of tokens.

Example:

"https://my-company-server.com"

code

string

Temporary authorization code received on the redirect_uri. Keep in mind that this code is only valid for 10 minutes. Use this parameter to create your first set of tokens.

Example:

"ory_ac_lY8t9YfHv3N2tLEKFfgL5_XADs2sbcxVGcYPbneMAAo.w-9CyjAz0DB-_3q2s5ZpYk-oFEUCBcMTU_s5iy07CA0"

refresh_token

string

Last refresh token. Use this parameter to refresh an existing access token.

Please note that your refresh token remains valid within a grace period of 60 seconds after its first usage, allowing multiple usages without immediate invalidation. When the grace period ends, the refresh token will be invalidated. This can be beneficial in scenarios where network issues or delayed token exchanges may otherwise disrupt session continuity.

Example:

"ory_rt_7kRxfEQzaBuL9RRSusC_vKRUNmtr1jdUC_i2NORdmZU.Ze-WLB5gZa7UIbhHSgv3KCpqvJHMZHUn6hgc1XOGoRU"

Response

Returns the set of tokens created. If you are receiving an HTML response, please make sure you've included the X-Qonto-Staging-Token header in your request.

access_token

string

required

Bearer token to use in the Authorization header of your API requests. This token is valid for 1 hour.

Example:

"ory_at_2-ocNFHnqdPjEOs9FdHMf6jKO4VNTVvLp3zChWVItoY.CaKVRy-plm-pr2mKk22Nt3ThgVjHmfkrolgTmMapvCI"

expires_in

integer

required

Access token lifespan in seconds.

Example:

3600

scope

string

required

List of scopes granted to your application.

Example:

"offline_access organization.read"

token_type

string

required

Type of token you have requested. It will always be bearer.

Example:

"bearer"

refresh_token

string

Token to exchange against a new access_token when it reaches its end of life. This token is valid for 90 days.

☝️ To receive the refresh token, you need to use the offline_access scope when retrieving an authorization code.

Example:

"ory_rt_7kRxfEQzaBuL9RRSusC_vKRUNmtr1jdUC_i2NORdmZU.Ze-WLB5gZa7UIbhHSgv3KCpqvJHMZHUn6hgc1XOGoRU"

id_token

string

JSON Web Token that contains information about the user and the session. It can be digitally verified by your application to create a session. This token is valid for 1 hour.

☝️ To receive the ID token, you need to use the openid scope when retrieving an authorization code.

Example:

"eyJhbGciOiJSUzI1NiIsImtpZCI6InByaXZhdGU6NzY4ZTk0OTYtMmJlOS00OTg4LTllNzUtZTU2NTEwODI5YzhjIiwidHlwIjoiSldUIn0.eyJhdF9oYXNoIjoiYVJUdFZBbndFX0RDblhSa1hhMnhxQSIsImF1ZCI6WyJsb2NhbGhvc3QtdGVzdC1jbGllbnQtYXBwIl0sImF1dGhfdGltZSI6MTc2MDAyMDQzMSwiZW1haWwiOiJvd25lckBxb250by5ldSIsImV4cCI6MTc2MDAyNDA4MywiaWF0IjoxNzYwMDIwNDgzLCJpc3MiOiJodHRwczovL29hdXRoLXNhbmRib3guc3RhZ2luZy5xb250by5jbyIsImp0aSI6IjBlYjQ3YjczLTI1NzgtNDQ3NC05MjNhLWQ3ZmQ4NTQ1NzJiYyIsInJhdCI6MTc2MDAyMDM1Mywic2lkIjoiZmYxYTY0MjgtOTdkZi00Yzc4LWJjOTgtM2JjMjVlNjM1MmQwIiwic3ViIjoiMDE5NjVkYzQtZmMxZi03ODc0LTgzYjQtYjU1MjhiZWEwYThkIn0.N2M3LiDbNvA115Foed1YVJ8mqr_mq_8-gmAJ6FkhWyx45gpUpeKji4U0lWbh3sYN1cd90aSwhZnrxxTxVsJAo6pvbWkw0ghzMasmltqAbxttPW-GgfieUh1ipbgE7ekmNPT6Op_qAU_E5OhZDKd01HC07on5FdVkdHeZGSN0ahZ4MezlmYA85Ig_qDM-7hW0DQhlATRuYpatl5hIE_7oiGsTrcsUgNYxoIILOCSP_FhHGJRtKah1wVqRhPu5fQG277mOTugI463yMDzAJMRgptEfpA02whnB6tycXKNfRDdFbYS1jxKzwSFTX3QAmhDWWJl4fgyAYe3ur_pD9jqlb9hpZwXFThJzfxyvKkPwiZjaVmWZi1dAhAzE2jZH6ktwimVbDjI3uWiOwz10AsYoTpZXf17jJRrR7bzj_ayYlh1G3JfIEPgiK4QkekWcV9uerWS_9ziyPqVOZw-sBEGZC19JcvMW1pzlK9az9aTKekBmzmCdXw9ankc_-1rfd9rB2oco_-_Vh9hKk5jHExHk0GZ1C48C-UZd7iB0VpQC7R_93gvHk3crIvyPqcZQl7PPBoqYK9thuliLpCkPhJ_nYX-2RDUfeI6wHL26hklCU3t-N-SAecZ34WBkk9S30cvY333HPZi1lNxEptc0obmjCMCYcSg0Sr_Ctk9Z8nXrMEU"

Retrieve an authorization code Revoke consents

⌘I

Business API

Onboarding API

Headers

Body

Response