Kontist Developer Portal | Welcome. Discover all the services of our platform so that you can build or integrate your service with Kontist.

The features described here require special environments and/or extended settings for your OAuth2 client. Please get in touch with us if you want to discuss your requirements.

Advanced Authentication

Device Binding

Some entities require strong customer authentication, so you need to pass multi-factor authentication (MFA) and get a confirmed access token. To avoid repeating push notifications some clients may use device binding.

Device Binding will only be possible if you can store a private key in a secure location (like e.g. a hardware-backed keystore).

To pass device binding authentication you need to generate a pair of private and public keys by using elliptic curve algorithm (secp256r1). To create and verify your device you need to pass your public key and then sign OTP from SMS received on your phone.

After that, you can use your device id and your private key to get your confirmed auth token by creating and verifying device challenge.

Create device binding request

Before you initiate the device binding you need to create a device binding request which then needs to be confirmed by the user on an existing (already and verified) device or via email.

Please see the createDeviceBindingRequest mutation. You can use the getDeviceBindingRequest query to check the status of the request. You have then 3 minutes to create and verify the device.

Create device

To initiate the device binding you need to create a device by providing your public key.

Please, make sure that you never share your private key and it’s stored in a secure place.

After a successful request, you will receive an SMS with OTP that you will need during device verification.

curl "https://api.kontist.com/api/user/devices" \
  -H "Authorization: Bearer ey..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
        "name": "iPhone XS",
        "key": "0402e86575939cd541f016b69b1bc6ee97736f7a6d32c0ad375695ffdc03acf21a3b54224fd164ad6f9cfdfb42b74f49f3d34a41f95d62e893be4977c7ec154f29"
      }'

The above command returns JSON structured like this:

{
  "deviceId": "4e310a55-1b1a-4efb-b9a5-fd04491bdd21",
  "challengeId": "4e310a55-1b1a-4efb-b9a5-fd04491bdd21"
}

HTTP Request

POST https://api.kontist.com/api/user/devices

Request body

Parameter	Mandatory	Description
name	yes	The name of the device
key	yes	The hex-encoded public key without header

Response

Field	Description
deviceId	ID of the device
challengeId	ID of the challenge

Verify device

To verify device you need to provide a signature of OTP received on your mobile phone.

curl "https://api.kontist.com/api/user/devices/4e310a55-1b1a-4efb-b9a5-fd04491bdd21/verify" \
  -H "Authorization: Bearer ey..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
        "challengeId": "4e310a55-1b1a-4efb-b9a5-fd04491bdd21",
        "signature": "30440220220B71BA03178A43B6CFA766F1B520CA1A626777F76B21253F9EC5039F4A0EB3022043CF2685C8F695F434862EADD1D5F5D6F68C29E875F755D058070A71E8338E11"
      }'

The above command returns 204 No Content in case of success.

HTTP Request

POST https://api.kontist.com/api/user/devices/{device_id}/verify

Request body

Parameter	Mandatory	Description
challengeId	yes	ID of the challenge recieved during device creation
signature	yes	The hex-encoded signature for the OTP recived in SMS

Create device challenge

After the device is created and verified, you need to create a device challenge. As a response, you will receive stringToSign that should be used during verification of device challenge.

curl "https://api.kontist.com/api/user/devices/4e310a55-1b1a-4efb-b9a5-fd04491bdd21/challenges" \
  -H "Authorization: Bearer ey..." \
  -X POST

The above command returns JSON structured like this:

{
  "id": "5f7c36e2-e0bf-4755-8376-ac6d0711192e",
  "stringToSign": "9e2d45df-9b00-49d3-9064-29b86374fe67"
}

HTTP Request

POST https://api.kontist.com/api/user/devices/{device_id}/challenges

Response

Field	Description
id	ID of the challenge
stringToSign	Challenge string that should be signed by device private key

Verify device challenge

To verify device challenge you need to provide a signature of stringToSign received after challenge creation. Performing this verification will grant you a confirmed access token giving you access to all banking APIs.

If the OAuth2 client involved uses refresh tokens, you will also obtain a confirmed refresh token with the response. Such a refresh token can be used to renew confirmed access tokens. This will allow you to perform the device challenge verification procedure only once for the whole lifetime of your refresh token.

curl "https://api.kontist.com/api/user/devices/4e310a55-1b1a-4efb-b9a5-fd04491bdd21/challenges/5f7c36e2-e0bf-4755-8376-ac6d0711192e/verify" \
  -H "Authorization: Bearer ey..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
        "signature": "FF93DF062DB808E35AB9D28D80E0B261C7313C69785471954C05A474156BA7A7F07F2F0E7E805513754A8119BBF172E1E6D0103901249CE8DE012E5E61FDA36AD06405341043"
      }'

The above command returns JSON structured like this:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI4ODNjNTc4ZS01M2QwLTRhYmEtOTBiNC02MmRmZmFkNTE5NTMiLCJzY29wZSI6ImF1dGgiLCJjbmYiOnsia2lkIjoiMmExNjRlYzYtZTJkNC00OTI4LTk5NDItZDU5YWI2Yzc4ZDU5In0sImlhdCI6MTU2NzQwOTExNSwiZXhwIjoxNTY3NDEyNzE1fQ.m35NDpQMAB5DMebXUxEzWupP3i-iAwoyVy2sGF1zp_8",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwMTIwMmUwZi0yOWE4LTRlNDgtODcyNi01OGFiMDAxNDBiNTgiLCJzY29wZSI6InJlZnJlc2ggYWNjb3VudHMgb2ZmbGluZSIsImNsaWVudF9pZCI6IjU4NjcwYmRhLWQxZDEtNGJlOC1hZGEyLTcwNjFkZWVhYjMxNyIsImNuZiI6eyJraWQiOiJlNTA3NTQ5NC1iNWM0LTRjYTEtYjE4MC01ZjNjNTBhNjA2OWMifSwiaWF0IjoxNTc2ODM2MDU5LCJleHAiOjE1NzY4NDMyNTl9.DydSAzxAFncGlWQMNZZp4q48EjAoz6FR6IboxTPx2j4"
}

HTTP Request

POST https://api.kontist.com/api/user/devices/{device_id}/challenges/{challenge_id}/verify

Request body

Parameter	Mandatory	Description
signature	yes	The hex-encoded signature for the `stringToSign`

Response

Field	Description
token	Auth token with confirmation claim that should be used for endpoints that require strong customer authentication
refresh_token	Refresh token with confirmation claim that can be used to renew confirmed access tokens

Setting up your own Multi-Factor Authentication flow

If you have implemented Device Binding, you can also setup your own Multi-Factor Authentication on top of it for environments not allowing you to store private keys (e.g. a web application).

You can follow all the steps of the push notification MFA flow that we provide, and setup your own challenge verification procedure.

Getting pending challenges

In your application with Device Binding, you can get all pending challenges for the current user:

curl "https://api.kontist.com/api/user/mfa/challenges" \
  -H "Authorization: Bearer ey..." \
  -H "Content-Type: application/json" \
  -X GET

The above command returns JSON structured like this:

[
  {
    "id": "b1ed17e9-2944-4c14-9780-57dce7f01ca8",
    "status": "PENDING",
    "expiresAt": "2019-12-05T09:02:22.319+00:00"
  },
  {
    "id": "08e9429c-5e21-4b1d-959d-c435a0f1cd99",
    "status": "PENDING",
    "expiresAt": "2019-12-05T09:02:24.641+00:00"
  }
]

HTTP Request

GET https://api.kontist.com/api/user/mfa/challenges

Verifying challenges

Then, if you are in possession of a confirmed token obtained with Device Binding, the MFA challenges can be verified by accessing this endpoint:

curl "https://api.kontist.com/api/user/mfa/challenges/b1ed17e9-2944-4c14-9780-57dce7f01ca8" \
  -H "Authorization: Bearer ey..." \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{
        "status": "VERIFIED"
      }'

The above command returns 204 No Content in case of success.

HTTP Request

PATCH https://api.kontist.com/api/user/mfa/challenges/{challenge_id}

Request body

Parameter	Mandatory	Description
status	yes	The status to update the challenge to. `VERIFIED` and `DENIED` are valid