Authorization

caution

Basic authentication is currently deprecated for the Jumio REST APIs.

All calls to Jumio REST APIs should be authorized using OAuth2 Bearer Tokens. You obtain the bearer token by calling the Access Token URL (OAuth2) for your region with your API token and secret values, which you can find in the Jumio Portal under:

Settings > Identity Verification > API credentials > OAuth2 Clients

info

A transaction-specific token is generated when you create or update an account. This token, used for uploading credentials and finalizing the workflow, is included in the response of the account creation or update call.

As a security best practice, requests for bearer tokens should be server-to-server, to avoid making your Client ID and Client secret values available to an end-user’s device. Regardless of the integration channel, the end-user’s device should notify your server when a token is required. Your server should make the call to the Jumio OAuth server, and then pass the token to the end-user device.

Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation. Access your Client ID and Client secret from the Portal. See API Credentials.

important

• OAuth 2.0 access tokens are valid for 60 minutes (3600 seconds) by default.
• To avoid unnecessary authentication requests, access tokens are cached internally, and consecutive calls may return the same token. To prevent 401 Unauthorized errors, refresh the token a few minutes before it expires. You can check the token’s expiration by decoding it and examining the exp (expiration) and iat (issued at) claims.
• For testing purposes, you can use Postman’s built-in OAuth 2.0 authorization type (under the Authorization tab), which can automatically retrieve and manage tokens across your requests or collections.

The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see Supported Cipher Suites.

Access Token URLs (OAuth2):

• US: https://auth.amer-1.jumio.ai/oauth2/token
• EU: https://auth.emea-1.jumio.ai/oauth2/token
• SG: https://auth.apac-1.jumio.ai/oauth2/token

note

Calls with missing, incorrect, or suspicious headers or parameter values will result in HTTP status code 400 Bad Request Error or 403 Forbidden. oauth2/token requests are subject to Rate Limits. The default rate limit is 10 per second. If the rate limit is reached, a HTTP 429 Too many requests status code is returned.

Example: Request Access Token

curl

curl --location 'https://auth.amer-1.jumio.ai/oauth2/token'\
    -u CLIENT_ID:CLIENT_SECRET \
    --header 'Accept: application/json'\
    --data-urlencode 'grant_type=client_credentials'

Python

import requests
from requests.auth import HTTPBasicAuth

client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
url = "https://auth.amer-1.jumio.ai/oauth2/token"

response = requests.post(
url,
auth=HTTPBasicAuth(client_id, client_secret),
headers={"Accept": "application/json"},
data={"grant_type": "client_credentials"}
)

Java Spring Boot

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import org.springframework.util.*;

public class OAuthClient {

    public static void main(String[] args) {
        String clientId = "CLIENT_ID";
        String clientSecret = "CLIENT_SECRET";
        String url = "https://auth.amer-1.jumio.ai/oauth2/token";

        RestTemplate restTemplate = new RestTemplate();

        // Set Basic Auth Header
        HttpHeaders headers = new HttpHeaders();
        headers.setBasicAuth(clientId, clientSecret);
        headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));

        // Create body
        MultiValueMap<String, String> body = new LinkedMultiValueMap<>();
        body.add("grant_type", "client_credentials");

        HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(body, headers);

        // Send POST request
        ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, request, String.class);

        System.out.println(response.getBody());
    }
}

PHP

<?php
$clientId = "CLIENT_ID";
$clientSecret = "CLIENT_SECRET";
$url = "https://auth.amer-1.jumio.ai/oauth2/token";

$data = http_build_query([
"grant_type" => "client_credentials"
]);

$options = [
    "http" => [
        "header" => [
            "Authorization: Basic " . base64_encode("$clientId:$clientSecret"),
"Content-Type: application/x-www-form-urlencoded",
"Accept: application/json"
],
"method" => "POST",
"content" => $data
]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);

if ($response === FALSE) {
die("Error occurred while making the request.");
}

echo $response;
?>

Typescript

import axios from "axios";
import qs from "qs"; // To encode form data

const clientId = "CLIENT_ID";
const clientSecret = "CLIENT_SECRET";
const url = "https://auth.amer-1.jumio.ai/oauth2/token";

async function fetchToken() {
    try {
        const response = await axios.post(
            url,
            qs.stringify({ grant_type: "client_credentials" }),
            {
                headers: {
                    "Accept": "application/json",
                    "Content-Type": "application/x-www-form-urlencoded",
                },
                auth: {
                    username: clientId,
                    password: clientSecret,
                },
            }
        );

        console.log(response.data);
    } catch (error) {
        console.error("Error fetching token:", error);
    }
}

fetchToken();