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.
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 create an API context, which you can do following these steps:
- register your API key and IP address(es) via
POST /installation(only once to activate your API key);
- register your device via
POST /device-server(only once to activate your API key);
- create a session via
There are a couple of ways to carry out the sequence of steps. Let's dwell on each of them.
- 1.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.
- 2.Create a DeviceServer via
POST v1/device-server. Provide a description and a secret (API key in this case).
- 3.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-serverrequest as an array. You must include your current IP in this array as to not lock yourself out.
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.