---
updatedAt: 2026-09-29T10:57:44.000Z
agentTools:
  projectIndex: https://docs.sumsub.com/llms.txt
---

# Generate Device Intelligence access token

# Overview

Once the applicant browser initiates a request to your website, apply this method with the corresponding session ID to generate an [access token](#access-token-example).

## Required permissions

To use this method, no particular [permission](https://docs.sumsub.com/sumsub/docs/user-roles#permissions) is required on the [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) — a valid API token is sufficient.

Your account must have **Device Intelligence** enabled — calling this method without it<br />enabled returns a `403`.

# Request example

```curl
curl -X POST \
     'https://api.sumsub.com/resources/accessTokens/behavior' \
     -H 'content-type: application/json' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>' \       
     -d '{
            "ttlInSecs": 1800,
            "sessionId": "session_id"
         }'
```

# Response explained

When you receive a response with the access token, use it at the next step to [start the JS library](https://docs.sumsub.com/sumsub/reference/get-started-with-device-intelligence), and at the last step to [confirm the applicant platform event](https://docs.sumsub.com/sumsub/reference/confirm-applicant-platform-event).

### Access token example:

```json
{
    "accessToken": "_act-jwt-ytr123qkAWM9Tb2LSS6yuP8EoLqJtWKVsmhE6AgaCav5E28JAJiJidzG2qZIjMECQ6UWsuboKvMeM1HEhPTWF1ZPqJxcdtP0N8opXwJdCZLfetv5Ui516CloG6nKT9YUaZ."
}
```

# 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](#automatic-refresh-handler) and [manual](#manual-update).

<Callout icon="🚧" theme="warn">
  ### 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](#use-the-same-sessionId).
</Callout>

## 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](https://docs.sumsub.com/sumsub/reference/get-started-with-device-intelligence)—when initializing the JS script. Refer to the example below for implementation details.

```javascript
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 <Glossary>Promise</Glossary> 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.

```javascript
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.

<Callout icon="👍" theme="okay">
  ### Tip

  You can combine both automatic and manual methods to ensure smooth and secure authentication flows.
</Callout>

## 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.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "sumsub-api",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.sumsub.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "X-App-Token",
        "in": "header",
        "x-default": ""
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/resources/accessTokens/behavior": {
      "post": {
        "summary": "Generate Device Intelligence access token",
        "description": "",
        "operationId": "generate-access-token-device-intelligence",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sessionId"
                ],
                "properties": {
                  "sessionId": {
                    "type": "string",
                    "description": "Unique identifier of the applicant session."
                  },
                  "ttlInSecs": {
                    "type": "integer",
                    "description": "Lifespan of a token in seconds. Default value is 1800 seconds.",
                    "default": 1800,
                    "format": "int32"
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```