Opening a Session
So, you want to start using the bunq API, awesome! To do this, you have to open a session in which you will be making those calls.
There 2 ways to get a production API key:
create an app in the developer portal, or
generate it in the bunq app (Profile → Security & Settings → Developers → API keys).
For sandbox You can use one of the following ways:
create a sandbox user in the developer portal;
generate an API key in the sandbox app (Profile → Security & Settings → Developers → API keys);
get an API key from Tinker;
run a cURL request (use
sandbox-user-companyto generate a business user):curl https://public-api.sandbox.bunq.com/v1/sandbox-user-person -X POST --header "Content-Type: application/json" --header "Cache-Control: none" --header "User-Agent: curl-request" --header "X-Bunq-Client-Request-Id: $(date)randomId" --header "X-Bunq-Language: nl_NL" --header "X-Bunq-Region: nl_NL" --header "X-Bunq-Geolocation: 0 0 0 0 000"
Production API keys are only usable on the production and sandbox API keys are only usable on the sandbox.
Sandbox keys contain a
sandbox_prefix while production keys do not have any noticeable prefixes.
Before you can start a session, you need to register your API key, device and IP address(es). You can do it following the sequence of calls described below.
Each call needs to be signed with your own private key. An Installation is used to tell the server about the public key of your key pair. The server uses this key to verify you are sending the subsequent calls.
Start by generating a 2048-bit RSA key pair. You can find examples in the source code of our SDKs.
On the headers page, you can find out about the mandatory headers. Make sure to set an Authorization header if you are working in the sandbox environment.
You do not need to use the X-Bunq-Client-Authentication or X-Bunq-Client-Signatureheaders in the POST /installationcall.
POST your public key to the Installation endpoint. Use \n for newlines in your public key.
Save the installation Token and server_public_key returned in the response. Use the Token in the Authentication header to register a DeviceServer and to start a SessionServer. Use server_public_key to verify the responses you will receive from the bunq API.
All the following calls made to the server must be sent from a registered device. POST /device-serverregisters your current device and the IP address(es) it uses to connect to the bunq API.
Use the Token you received in the X-Bunq-Client-Authenticationheader of the response to POST /installation.
Make sure you sign your call, passing the call signature in the
X-Bunq-Client-Signatureheader.
Use your API key for the secret parameter. If you want to create and use another API key assign it to one or multiple IP addresses using POST /device-server within 4 hours before it becomes invalid. As soon as you start using your API key, it will remain valid until the next sandbox reset.
To make any calls besides /installation and /device-server, you need to open a session.
Use the Token you received in the X-Bunq-Client-Authenticationheader of the response to POST /installation .
Make sure you sign your call, passing the call signature in
X-Bunq-Client-Signatureheader.
Use your API key for the secret parameter.
Use the Token received in the response to POST /session-server to authenticate your calls in this session. Pass this session Token in the X-Bunq-Client-Authentication header with every call you make in this session.
