Authentication
Here is what you need to know about how the bunq authentication works:
All requests must use HTTPS. HTTP calls will fail.
We use extra signing on top of HTTPS encryption that you must implement yourself if you are not using the SDKs.
We use asymmetric cryptography for signing requests and encryption.
The client (you) and the server (bunq) must have a pair of keys: a private key and a public key. You need to pre-generate your own pair of 2048-bit RSA keys in the PEM format aligned with the PKCS #8 standard.
The parties (you and bunq) exchange their public keys in the first step of the API context creation flow. All the following requests must be signed by both your application and the server. Pass your signature in the X-Bunq-Client-Signature header, and the server will return its signature in the X-Bunq-Server-Signature header.
You should use SSL Certificate Pinning and Hostname Verification to ensure your connection with bunq is secure.
The auto logout time that you set in the app applies to all your sessions including the API ones. If a request is made 30 minutes before a session expires, the session will automatically be extended.
Before you can start calling the bunq API, you must do the following:
register your API key and IP address(es) via
POST /installation;register your device via
POST /device-server;create a session via
POST /session-server.
We call this intro "creating an API context". There are a couple of ways to carry out the sequence of steps. Let's dwell on each of them.
Go to our GitHub page.
Choose the SDK in your language of choice.
Find and use the part dedicated to creating an API context.
Run Tinker to see a sample project using bunq SDKs in action.
Create an Installation by calling
POST v1/installationand passing your pre-generated public key. You will receive an installation Token. Use it when making the two following API calls.Create a DeviceServer via
POST v1/device-server. Provide a description and a secret (API key in this case).Create a SessionServer by executing
POST v1/session-server. You will receive an authentication Token. Use it in the API requests in this active session.
Import our Postman collection to see our pre-setup API context creation calls. It will automatically generate and pre-fill everything in the API calls that create context so you can inspect the process.
When you create a context in POST v1/device-server, it ties the API key to your current IP address so it will not be useable from other IPs.
If you have several IPs (e. g. several servers), you can set a list of allowed IPs in device-server request as an array. You must include your current IP in this array as to not lock yourself out.
As a last resort, you can also set a wildcard as an IP. In that case there will be no IP check for that API key. Please only do that if you have no other option.
It is possible to add trusted IP addresses using the IP endpoint. Obviously you need to make that request from an IP address that was allowed previously.
You will not be able to switch from concrete IPs to a wildcard IP after you've created a device-server. You can either request a new API key from the user or ask them to use Allow all IP Addresses option in the app.
