Authorization
Jumio REST APIs use OAuth 2.0 bearer tokens to authorize API requests. Before accessing Jumio services, your application must obtain an access token using its Client ID and Client Secret.
Basic authentication is deprecated for direct authorization of Jumio REST API requests. Use OAuth 2.0 bearer tokens instead
Prerequisites
Before generating an access token, ensure that:
- OAuth 2.0 is enabled for your Jumio account. Contact your Jumio Account Manager if activation is required.
- You have obtained your Client ID and Client Secret from the Jumio Portal under Settings > Identity Verification > API Credentials.
- You have identified the appropriate regional endpoint for your integration.
For more information, see API Credentials.
Generate an OAuth 2.0 Access Token
To authorize requests to Jumio REST APIs, obtain an OAuth 2.0 access token using the client credentials grant.
- Select the OAuth 2.0 token endpoint for your region.
- Send a POST request to the token endpoint using your Client ID and Client Secret as HTTP Basic authentication credentials.
- Set the grant_type parameter to client_credentials.
- Retrieve the access token from the response.
- Include the token in the Authorization header of subsequent Jumio REST API requests using the Bearer scheme.
Regional Access Token URLs
Use the endpoint corresponding to your Jumio account's region.
| Region | Access Token URL (OAuth 2.0) |
|---|---|
| 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 |
Example: Request Access Token
The following example demonstrates how to request an OAuth 2.0 access token using cURL.
- curl
- Python
- Java Spring Boot
- PHP
- Typescript
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'
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"}
)
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
$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;
?>
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();
The HTTP Basic authentication method shown above is used only to authenticate your application when requesting an OAuth 2.0 access token. It should not be used to authorize subsequent Jumio REST API requests.
Use the Access Token
After obtaining an access token, include it in the Authorization header of subsequent API requests.
Authorization: Bearer YOUR_ACCESS_TOKEN
Access Token Validity and Refresh
- 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.
Transaction-Specific Tokens
In addition to OAuth 2.0 access tokens, Jumio provides transaction-specific tokens when you create or update an account.
These tokens are returned in the account creation or update response and are used for operations associated with that transaction, including credential uploads and workflow finalization.
OAuth 2.0 access tokens authorize requests to Jumio REST APIs, whereas transaction-specific tokens are used for designated operations within an individual verification transaction. These tokens are not interchangeable.
Security Best Practices for Token Handling
To protect your API credentials and access tokens, follow these recommendations:
1. Use server-to-server authentication: Generate OAuth 2.0 access tokens on your backend server rather than directly from an end-user's device.
2. Protect client credentials: Never expose your Client ID or Client Secret in client-side code, mobile applications, or publicly accessible repositories.
3. Store tokens securely: Prevent unauthorized access to tokens and avoid logging sensitive authentication information.
4. Use secure communication: Transmit credentials and tokens only over HTTPS using TLS.
5. Manage token expiration: Implement token reuse and expiration handling to minimize authentication failures.
For integrations involving an end-user device, route authentication requests through your backend to keep sensitive credentials protected.
Transport Security Requirements
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.
Rate Limits and Error Handling
The OAuth 2.0 token endpoint is subject to rate limiting. The default rate limit is 10 requests per second.
The following HTTP status codes may be returned when authentication requests fail.
| HTTP Status | Description | Recommended Action |
|---|---|---|
400 Bad Request | The request contains missing, invalid, or incorrectly formatted parameters. | Verify the request parameters and required headers. |
401 Unauthorized | Authentication or authorization has failed, such as when an access token is invalid or expired. | Verify the credentials or obtain a valid access token, as applicable. |
403 Forbidden | The request is forbidden, potentially because of suspicious or disallowed request values. | Verify the request and contact Jumio Support if the issue persists. |
429 Too Many Requests | The API rate limit has been exceeded. | Reduce request frequency and implement retry handling with backoff. |
Testing in Postman
You can use Postman's built-in OAuth 2.0 authorization functionality to test Jumio REST APIs.
- Open your request or collection in Postman.
- Navigate to the Authorization tab.
- Select OAuth 2.0 as the authorization type.
- Configure the client credentials grant using your Client ID, Client Secret, and regional access token URL.
- Generate an access token and use it to authorize your API requests.
Postman can manage access tokens across requests or collections, simplifying API testing.