Introduction

The Interactive APIs allows end users to manage their BindID account, such as adding new trusted devices. These endpoint are available:

• /interactive/init: used to request a BindID account action from your application.
• /interactive: used to initiate an end-user BindID interactive flow that updates the user's account. The flow is initiated using the response received from calling /interactive/init, and all pages and screens use your application's custom branding.

Base URL

The Flow Initialization API is served over HTTPS, and provided as endpoints under:

https://<host-name>

where <host-name> has the following value depending on the environment:

• Sandbox: api.bindid-sandbox.io
• Production: api.bindid.io
• Production EU: api.eu.bindid.io

Authorization

For the Flow Initialization API endpoint, authentication is performed using an OAuth2 Access Token in the Authorization request header field.

The Authorization header value should have the following form, where the tokens are replaced according to the descriptions below:

BindIdBackend AccessToken [<accesstoken>;] <authvalue>

Token	Description
<accesstoken>	Access token associated with the request.
<authvalue>	Base-64 encoded HMAC-SHA256 on the access token associated with the request, where the HMAC is calculated using the service provider client secret as the key (see the Java code sample below).

This sample Java code generates the <authvalue> and constructs the Authorization header value:

import javax.crypto.Mac;

import javax.crypto.spec.SecretKeySpec;

import java.io.UnsupportedEncodingException;

import java.nio.charset.StandardCharsets;

import java.security.InvalidKeyException;

import java.security.NoSuchAlgorithmException;

import java.util.Base64;

public static String calculateAuthorizationHeaderValue(String clientSecret, String bindIdAccessToken) throws

UnsupportedEncodingException, InvalidKeyException, NoSuchAlgorithmException {

// Create and initialize the Mac instance

Mac mac = Mac.getInstance("HmacSHA256");

byte[] keyBytes = clientSecret.getBytes(StandardCharsets.UTF_8);

SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "HmacSHA256");

mac.init(keySpec);

// Calculate the MAC on the BindID AccessToken

byte[] signedBytes = mac.doFinal(bindIdAccessToken.getBytes(StandardCharsets.UTF_8));

// Encode the signed bytes to base64

String encodedResult = Base64.getEncoder().encodeToString(signedBytes);

// Create the Authorization Header value

return "BindIdBackend AccessToken " + bindIdAccessToken + "; " + encodedResult;

}

Errors

The following types of errors will be returned in case of failure.

Unauthorized

For an API call specifying an invalid access token or one that does not belong to the authenticating client ID, the response will be an HTTP 403 Forbidden response:

HTTP/1.1 403 Forbidden

Others

Each API may indicate other failure responses. All APIs may also return a 500 error in case of an internal server error.