Device Registration

Registering a device links the API key to a specific phone, computer, or server. This prevents stolen or exposed keys from being used on untrusted devices.

By using POST /device-server, bunq ensures that only pre-approved machines can make API calls. This approach is crucial in banking, where unauthorized access could lead to financial fraud. Unlike simple API keys, this extra layer significantly reduces attack surfaces by restricting access to known, registered devices.

Ensure you have a bunq API Key. You can generate one from the bunq APP if you haven't already.

IP addresses

When you use a standard API Key, the DeviceServer and Installation are linked to the IP address where they were created. You won’t be able to add new IP addresses later.

Using a Wildcard API Key gives you the freedom to make API calls from any IP address after the POST device-server. You can switch to a Wildcard API Key by tapping on “Allow All IP Addresses” in your API Key menu inside the bunq app. You can also programatically switch to a Wildcard API Key by passing your current ip and a * (asterisk) in the permitted_ips field of the device-server POST call.

Payload example:

{
	"description": "My awesome APP",
	"secret": "{api_key}",
	"permitted_ips": ["1.2.3.4", "*"]
}

Code samples for the device-server endpoint:

Pass the installation_token received in the last step as value for the header X-Bunq-Client-Authentication to authenticate yourself in this endpoint.

post

Create a new DeviceServer providing the installation token in the header and signing the request with the private part of the key you used to create the installation. The API Key that you are using will be bound to the IP address of the DeviceServer which you have created.Using a Wildcard API Key gives you the freedom to make API calls even if the IP address has changed after the POST device-server.Find out more at this link https:/bunq.com/en/apikey-dynamic-ip.

Header parameters

Cache-ControlstringOptional

The standard HTTP Cache-Control header is required for all signed requests.

User-AgentstringRequired

The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.

X-Bunq-LanguagestringOptional

The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.

X-Bunq-RegionstringOptional

The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.

X-Bunq-Client-Request-IdstringOptional

This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.

X-Bunq-GeolocationstringOptional

This header must specify the geolocation of the device. The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.

X-Bunq-Client-AuthenticationstringRequired

The authentication token is used to authenticate the source of the API call. It is required by all API calls except for POST /v1/installation. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call

Body

descriptionstringRequired

The description of the DeviceServer. This is only for your own reference when reading the DeviceServer again.

secretstringWrite-onlyRequired

The API key. You can request an API key in the bunq app.

permitted_ipsstring[]Write-onlyOptional

An array of IPs (v4 or v6) this DeviceServer will be able to do calls from. These will be linked to the API key.

Responses

post

HTTPcURLJavaScriptPython

POST /v1/device-server HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "description": "text",
  "secret": "text",
  "permitted_ips": [
    "text"
  ]
}

{
  "id": 1
}

What's next

With the installation_token in hands, we are able to authenticate ourselves and register our device for future endpoint calls.