Overview

Once the applicant browser initiates a request to your website, apply this method to generate an access token with the corresponding session ID.

When you receive a response with the access token, use it at the next step to start the JS library, and at the last step to confirm the applicant platform event.

Access token example:

{
    "accessToken": "_act-jwt-eyx8A8qkAWM9Tb2LSS6yuP8EoLqJtWKVsmhE6AgaCav5E28JAJiJidzG2qZIjMECQ6UWsuboKvMeM1HEhPTWF1ZPqJxcdtP0N8opXwJdCZLfetv5Ui516CloG6nKT9YUaZ."
}

Access token update

The access token has a limited lifespan and will eventually expire. There are two built-in mechanisms to handle token refresh: automatic and manual.

🚧

Attention

When obtaining an updated access token, use the same sessionId to associate the old session with the new when possible. For details, refer to the paragraph below.

Automatic refresh handler

Automatic token refresh is internally triggered by Device Intelligence when a 401 Unauthorized error occurs during a request.

You can enable this function during the second step of the Device Intelligence integration—when initializing the JS script. Refer to the example below for implementation details.

import { init } from '@sumsub/fisherman'
 
const getAccessToken = () => {
   // get access token using sessionId
}
 
const token = await getAccessToken()
const accessTokenUpdateHandler = async () => await getAccessToken()
 
const fisherman = await init({
  token,
  accessTokenUpdateHandler
})

The function returns a Promise that resolves to a new access token string.

• If the Promise resolves to undefined or is rejected, the token will be removed.
• If a valid token is returned, the library will automatically retry the failed request using the new token.

Manual update

The following function allows you to proactively update the access token from outside the fisherman library, without requiring a failed request to initiate the refresh process. Refer to the example below for implementation details.

import { updateAccessToken } from '@sumsub/fisherman'
 
const getAccessToken = () => {
   // get access token using sessionId
}
 
window.addEventListener('focus', async () => {
  const newToken = await getAccessToken()
  updateAccessToken(newToken)
})

This function is useful in the following scenarios:

• When the user returns to the page after an extended period of inactivity.
• When your application renews the session on the backend.
• When a new token is obtained via a background request, such as through a cookie.

👍

Tip

You can combine both automatic and manual methods to ensure smooth and secure authentication flows.

Use the same sessionId

Use the same sessionId when refreshing the access token, if possible.

Maintaining the same sessionId ensures that the new session remains logically linked to the original one. By maintaining a consistent sessionId, Sumsub can correlate historical and newly collected device signals, ensuring continuity of behavioral tracking and improving fraud detection accuracy. Using a consistent sessionId is critical for effective fraud detection, especially in workflows that rely on trust context, session reputation, or behavioral history.

When a new sessionId is used instead, it initiates a separate context, and historical device signals will not be associated automatically. This can lead to fragmented tracking, reduced analytical accuracy, and potentially weaker fraud detection—particularly in scenarios that rely on identifying repeated patterns or anomalies across sessions.