Introduction

The Service Provider Backend APIs allow you to manage custom data for your users.

Base URL

The Service Provider Backend APIs are 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

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. If not present, the access token will be taken from the subject_session_at field in the body if present; otherwise, an unauthorized response is returned. If the access token is passed in both the header and body, they must match. Note that some requests may require a subject_session_at field in the body.
<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

Applicative

Applicative failure cases will be reported as an HTTP 200 OK response, with an application/json header and a JSON body with the following structure:

Field Name	Description	Type
status_code	A symbolic error code.	String

For example:

HTTP/1.1 200 OK

Content-Type: application/json

{

"status_code": "12345"

}

Others

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