Troubleshooting

This guide will help you diagnose and resolve common authentication and connection issues with the Qonto API.

Step 1: Choose your authentication method

Before making any API calls, determine which authentication method you’ll use:

• Static API Key - A login/secret pair provided by Qonto
• OAuth - Token-based authentication using the OAuth 2.0 flow

Not sure which to use? We have a detailed guide here explaining the differences & supported endpoints for each authentication method.

Step 2: Test with a simple endpoint

Make a test call to the List Bank Accounts endpoint to verify your setup.

GET /v2/bank_accounts

Step 3: Diagnose the response

✅ Got a success response code? (2XX)

Expand the section below based on what you received:

✅ Received JSON Response

Congratulations! You’re successfully authenticated and connected to the Qonto API.

You can now proceed with making other API requests.

❌ Received HTML (OneLogin Page)

Issue: You’re trying to access the Staging environment without proper Staging Token.

Solution: Add the X-Qonto-Staging-Token header to your request. This token can be found in the developer portal.

X-Qonto-Staging-Token: your-staging-token-here

The Sandbox environment requires the staging token header in addition to your regular authentication credentials.

❌ Got an error response? (4XX)

Follow the troubleshooting steps for your authentication method:

Static API Key

Verify your API key format

Please follow the documentation here for static API key.

Your static API key must be provided in the Authorization header using HTTP Basic Authentication format:

Authorization: {login}:{secret}

Example:

Authorization: your-login-here:your-secret-here

Do not include “Basic” before the credentials - use the raw {login}:{secret} format directly.
Some users confuse this with basic authentication, but it is not.

Common mistakes

• Missing the colon separator: loginSecret
• Swapping login and secret: {secret}:{login}
• Adding a “Bearer” prefix before the login & secret
• Adding a “Basic” prefix before the login & secret
• Including extra spaces or line breaks
• Base64 encoding when not required

OAuth

Verify your access token format

Please follow the documentation here for OAuth access.

Your OAuth access token must be provided in the Authorization header with the Bearer scheme:

Authorization: Bearer {accessToken}

Example:

Authorization: Bearer eyJhbGciOi...

The keyword “Bearer” must be included, followed by a space, then your access token.

Common Mistakes

• Missing “Bearer” prefix
• Using an expired access token
• Including extra characters or line breaks
• Using the refresh token instead of the access token

Access tokens typically expire after a set period. If you’re getting authentication errors, try refreshing your token.

Still stuck? Contact Qonto support

If you are unable to resolve the issue, reach out to the Qonto team. To help us investigate as quickly as possible, include a trace identifier from the failing response. You can use either of the following—they always match on error responses:

• The X-Tyk-Trace-Id response header (present on every API response):

X-Tyk-Trace-Id: 6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c

• The trace_id field in the JSON body (always included on error responses):

{
  "errors": [ ... ],
  "trace_id": "6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c"
}

Error responses always include trace_id in the JSON body, and every API response includes an X-Tyk-Trace-Id header. Copy either value and attach it to your support request—they identify the same request and speed up troubleshooting significantly.