Skip to main content

Quickstart Guide: Authentication

Prerequisites​

To initiate the Jumio Authentication Workflow, you must have an existing basis for verification (i.e., a valid selfie). Examples include:

  • A completed workflow with a "PASSED" liveness decision (liveness.decision = PASSED).
  • A previously captured selfie using Jumio’s user interface (preferred), or an image enrolled via API.

Step-by-Step Process​

Step 1: Authenticate and Get OAuth2 Bearer Token​

  • Generate an OAuth2 Bearer token by calling the /token endpoint with the POST HTTP method.
  • Use Basic Authentication with the client ID and client secret found in the settings section of your Jumio Portal.
  • Once obtained, include the token in the Authorization header for all subsequent API requests.
tip

Refer to the Authentication documentation for the specific endpoint to obtain this token.

Access Token URLs (OAuth2)​

Accept: application/json

Body (x-www-form-urlencoded)​

grant_type=client_credentials

Example Response​

{
  "access_token": "<your_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
note
  • OAuth 2.0 access tokens are valid for 60 minutes (3600 seconds) by default.
  • To avoid unnecessary authentication requests and reduce integration costs, do not call the /auth endpoint before every transaction. Instead, reuse the same access token until it expires, and request a new one only when needed.
  • For testing purposes, you can use Postman's built-in OAuth 2.0 authorization type (under the Authorization tab), which allows you to retrieve and manage tokens automatically across your requests or collections.
  • For a step-by-step walkthrough, check out this short video guide.

Step 2: Update an Account for Authentication​

Trigger an account and update by calling the /accounts endpoint with the PUT method.

The body must include a valid workflowDefinition with key 10014.

Endpoint​

https://account.{{api_endpoint}}.jumio.ai/api/v1/accounts/{{accountId}}

Region-Specific Endpoints​

Example Request​

{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    "key": 10014
  }
}

Example Response​

{
{
   "timestamp": "2025-06-17T15:44:48.584Z",
   "account": {
       "id": "UUID"
   },
   "web": {
       "href": "https://jumio-go.web.emea-1.jumio.ai/web/client?baseUrl=https%3A%2F%2Fweb-sdk.emea-1.jumio.ai%2Fwebsdk%2Fv4%2Fapi&authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMOw4CMQxF0a2g1FiKHdtJ6JBopmUHzq9CQwESSIi9k4EV0F6d916uP493d3AYhaJGn5IEdHtntS5tdkuoQytCoCzAAz1k7gxoRakoshXe-A_HUJtag6GFgUNLkDj2uZUQfbOuXCd-jP4Pr-c-pl5Ou9vd1maX69q3_P3IQoGlCKRYCJgygRETiGCtvgfB0Nz7A6HwtdPnAAAA.Qgkm4uSfXqK5c1bZqZwRz1ZdihFvEWgnfZa6LaldH8mavc-fcLyFShAck72_OIVOPMcDFr_ofH7dBLIFsctcdA&locale=it"
   },
   "sdk": {
       "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMOw4CMQxF0a2g1FiKHdtJ6JBopmUHzq9CQwESSIi9k4EV0F6d916uP493d3AYhaJGn5IEdHtntS5tdkuoQytCoCzAAz1k7gxoRakoshXe-A_HUJtag6GFgUNLkDj2uZUQfbOuXCd-jP4Pr-c-pl5Ou9vd1maX69q3_P3IQoGlCKRYCJgygRETiGCtvgfB0Nz7A6HwtdPnAAAA.Qgkm4uSfXqK5c1bZqZwRz1ZdihFvEWgnfZa6LaldH8mavc-fcLyFShAck72_OIVOPMcDFr_ofH7dBLIFsctcdA"
   },
   "workflowExecution": {
       "id": "UUID",
       "credentials": [
           {
               "id": "UUID",
               "category": "FACEMAP",
               "allowedChannels": [
                   "WEB",
                   "SDK"
               ]
           },
           {
               "id": "UUID",
               "category": "SELFIE",
               "allowedChannels": [
                   "WEB",
                   "SDK"
               ]
           }
       ]
   }
}

Step 3: Complete the Authentication Workflow​

Option 1: Jumio Hosted Interface​

Use workflowExecution.web.href in one of the following ways:

  • Redirect to a browser tab
  • WebView in a mobile app
  • iFrame embedded in your website:
<iframe src="https://hosted.jumio.com/workflow/abc123" width="100%" height="700"></iframe>

Option 2: Jumio SDKs​

Use workflowExecution.sdk.token to initialize the SDK. Refer to Jumio’s SDK documentation for full implementation guidance.

Step 4: Retrieve Workflow Details​

Use the Workflow Retrieval API to obtain the full outcome.

Endpoint URL​

https://retrieval.{{api_endpoint}}/api/v1/workflow-executions/{{workflow_execution_id}}

Example Response​

{
  "workflow": {
    "id": "UUID",
    "status": "PROCESSED",
    "definitionKey": "10014",
    "customerInternalReference": "transaction_1234"
  },
  "account": {
    "id": "UUID"
  },
  ...
  "decision": {
    "type": "PASSED",
    "details": {
      "label": "PASSED"
    },
    "risk": {
      "score": 0.0
    }
  }
}

The response retrieved will contain the detailed outcome of the Authentication process.

For further details, advanced use cases, or support with customization, please refer to the complete API documentation or contact Jumio support.

Table of Contents