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.

Getting an API key

There 2 ways to get a production API key:

1. create an app in the developer portal, or

2. 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-company to 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.

Call Sequence

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.

1. POST /installation

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.

Headers

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.

Body

POST your public key to the Installation endpoint. Use \n for newlines in your public key.

Response

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.

2. POST /device-server

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.

Headers

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 theX-Bunq-Client-Signature header.

Body

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.

3. POST /session-server

To make any calls besides /installation and /device-server, you need to open a session.

Headers

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.

Body

Use your API key for the secret parameter.

Response

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.