Skip to main content

​
Why your Sandbox requests get blocked

Our entire Sandbox / staging environment — every API host, every web app, every URL it returns to you — is protected and not directly accessible from the public internet. If you try to reach any Sandbox URL without the right credentials, your request hits a OneLogin sign-in page first. That page is the SSO that protects internal Qonto resources: it is reserved for Qonto employees, and external partners cannot sign in through it. You will see this OneLogin page in two situations:
  • The API returns an HTML response (the OneLogin login HTML) instead of the JSON you expected — sometimes with a 200 status, sometimes as a 302 redirect to https://qonto.onelogin.com/login.
  • A URL the API gave you (a redirection_link from the Onboarding API, an attachment URL from the Business API, etc.) opens a OneLogin page when you click it.
To use the Sandbox, you need to bypass that OneLogin page. There are exactly two ways to do it, and they apply to two different situations.
Both bypass mechanisms are Sandbox-only. In Production they are unnecessary — and the staging token is not even accepted there.

​
Option 1 — Programmatic calls: the X-Qonto-Staging-Token header

Our entire Sandbox / staging environment is protected by a OneLogin gate and is not directly accessible from the public internet. For any non-browser call (cURL, your backend code, your HTTP client library, Postman, etc.), add the following header on every request you make to a Sandbox endpoint: When this header is present and valid, our infrastructure transparently bypasses the OneLogin gate and routes the request to the actual API.
The header name is case-sensitive on the dash-separated capitalization shown above: X-Qonto-Staging-Token. Lowercase or mixed variants may not be normalized by every layer in the chain.
The staging token is Sandbox-only: Production endpoints don’t accept it.
Where to find your staging token: your staging token is available on the Developer Portal, under your application’s authentication credentials. It is personal to your application — do not share it. The header must be present on every Sandbox request, including: To open a Sandbox URL in a browser (for example an Onboarding redirection_link or an attachment URL), the header can’t be used: see Accessing the Sandbox environment.

​
Example

​
Option 2 — Browser calls: log in through the Developer Portal first

Use this whenever a URL must be opened in a web browser — typically:
  • The redirection_link returned by the Onboarding API when you create a registration. The end-user customer is supposed to follow it to start their account creation.
  • Attachment URLs returned by the Business API when you retrieve transactions, supplier invoices, etc. Those URLs point to short-lived signed assets hosted on a Sandbox domain.
  • Any other Sandbox URL you need to reach interactively for testing.
You can’t add a custom header from a browser address bar, so the staging token approach doesn’t apply. Instead, you authorize your browser once through the Developer Portal:
1

Log in to the Developer Portal

Sign in at https://developers.qonto.com/ with your account.
2

Click "Sandbox web app" from the Toolkit

From the Developer Portal Toolkit, click the Sandbox web app link. This opens the Sandbox web app and sets a cookie in your browser that authorizes Sandbox domains.Sandbox web app login screen
3

Open your Sandbox URL in the same browser

Reuse the same browser (and the same profile) to open the redirection_link, attachment URL, or other Sandbox URL. The cookie set in step 2 lets you bypass the OneLogin gate and reach the actual page.
The cookie has a limited lifetime. If a Sandbox URL starts redirecting you to OneLogin again, simply re-click Sandbox web app from the Toolkit to refresh it.
The cookie is browser-scoped. If you open the URL in a different browser, an incognito/private window, or a different machine, you will see the OneLogin page again — even if you are already logged in to the Developer Portal in another browser. Click the Sandbox web app link from that browser to authorize it.

​
Which option do I need?

​
Troubleshooting

You forgot the X-Qonto-Staging-Token header, or the value is wrong. See Option 1.
Cookies don’t cross browsers or profiles. Click Sandbox web app from the Developer Portal Toolkit in whichever browser you actually want to use.
No. The X-Qonto-Staging-Token header is Sandbox only. Production endpoints don’t accept it. See Developer guidelines — Release your integration.