Background
The Qonto API authenticates users with an access token. This token must be kept secret and should never be exposed in client-side code. To achieve this, the Embed API and SDK provide a secure mechanism to proxy requests through your server.In addition to the access token, the staging token is another piece of
sensitive information that must be kept secret. When using the staging
environment, include the staging token in the request headers when calling the
Qonto API.
System Overview
The Qonto API provides a proxy endpoint that dispatches requests to other Qonto API endpoints. It expects a base64-encoded string that describes the call to be made to the target endpoint. Upon receiving this request, the proxy endpoint decodes the string and makes the request to the Qonto API on your behalf. The response is then returned to the caller, also base64-encoded. When using the Qonto SDK, you don’t need to handle the encoding/decoding of calls, the SDK manages this automatically. The overall flow involves creating an intermediary endpoint on your server that forwards requests prepared by the SDK to the Qonto API while including the access token in the request headers. This way, client-side code never has access to the access token, keeping it secure on your server. Here are the steps involved in the process shown in the diagram above:1
Define the proxyRequestFunction
Initialize the SDK with a
proxyRequestFunction
parameter that calls your
intermediary endpoint. Since only you know your endpoint details and how to
call it, providing your implementation is how the SDK knows how to reach
your intermediary endpoint.2
Use the SDK normally
Once the SDK is initialized, you can use it as you normally would. Call any
SDK function and await the response from your application.
3
The SDK uses the proxyRequestFunction to call your intermediary endpoint
When the SDK prepares the call to the API endpoint related to the function
you called, it encodes the request and calls the
proxyRequestFunction
you
provided during initialization.4
Add the access token to the request in your intermediary endpoint
The intermediary endpoint receives the encoded request. It must make a
request to the Qonto proxy endpoint including the access token as the
Authorization
header and the payload it receives as the data
parameter
in the body.5
Get the response from Qonto API and return it to the SDK
Once your intermediary endpoint receives the response from the Qonto API, it
returns it to the SDK without modification and in plain text format.
6
The SDK returns the response to your app
Once the SDK gets the response from your intermediary endpoint, it decodes
the response and returns it to your application.
Example Implementation
Let’s implement a call to update a SEPA beneficiary using the proxy endpoint.Step 1: Create the intermediary endpoint in your backend
We’ll assume an application written in TypeScript with Next.js. The intermediary endpoint will be created in the/app/api/embed-intermediary.ts
file as a Next Route Handler:
The intermediary endpoint needs to be implemented only once and will be used
for all SDK functions your application calls.
Step 2: Configure the SDK to call the intermediary endpoint from client-side code
On the client side, configure the SDK to call the intermediary endpoint you just created. Do this by passing theproxyRequestFunction
option to the SDK initialize
function:
The
proxyRequestFunction
needs to be implemented only once and will be used
for all SDK functions your application calls.