# How device sessions work

Device sessions are a built-in mechanism that maintain continuous communication with Fraud Prevention services for telemetry and event collection. These sessions are created automatically by the Fraud Prevention SDK during initialization and are refreshed periodically according to internal security and communication rules. A device session token uniquely identifies the device session to Mosaic.

The Fraud Prevention device sessions and device session tokens are independent of user logins, browser sessions, or application sessions. As a developer, you shouldn't be concerned with managing device sessions or synchronizing with user login or app sessions on your end. Because a device session represents the physical device rather than a specific user or browser session, multiple users using the same device may share the same device session.

Important
There is no need to manage or validate device sessions. These are managed and consumed entirely by the Fraud Prevention SDKs and Mosaic server.

Session tokens are short-lived and shouldn't be cached.

## How device sessions are utilized

A device session is created upon the SDK initialization and the SDK immediately starts sending telemetry data to Mosaic. The telemetry data is associated with a specific device session and identified using the device session token. The device session token can be requested by the app and returned by the Fraud Prevention SDK.

During the device session:

- The SDK triggers user actions. Alternatively, you can report events via backend API calls.
- Reporting the user ID for the login event builds an association between the user and their actions for the duration of the device session, which allows building a more reliable risk profile.
- When the device session expires, the user is automatically cleared, or you can do this explicitly before expiration.
- Device sessions are automatically refreshed by the SDK—there is no need for your app to manage token expiration or manually refresh it. To enable support for retrieving a device session token, set `enableSessionToken: true` when initializing the SDK.


For more information on maintaining user identity, see [this guide](/guides/risk/maintaining_user_identity).


```mermaid
sequenceDiagram
  participant app as Your app
  participant drssdk as Fraud Prevention SDK
  participant M as Mosaic
app-->>drssdk: Initialize SDK
drssdk->>drssdk: Create device session <br>(generate device session token)
opt Within the device session
  drssdk->>M: Telemetry
  app-->>drssdk: getSessionToken() or getSecureSessionToken() (optional)
  drssdk-->>app: Return session_token
  Note over app, M: Trigger action events (via SDK or API)
end
```

## Understand session token types

Mosaic supports two types of device session tokens for Fraud Prevention:

- **Regular device session tokens** ensure continuity of communication between a device and the Fraud Prevention SDK.
- **Secure device session tokens** extend regular device session tokens by providing stronger binding to the device and to a **single action type**, with an optional custom expiration time. Secure tokens are device-bound, which helps prevent session token injection attacks. Each call to `getSecureSessionToken()` returns a new token. Each secure session token is valid only for a specific action type it was created and must not be reused for different actions within the same device session.


Use secure tokens for high-risk actions (login, transaction, account changes); use regular tokens for low-risk operations. Both can coexist in the same application.

Backward compatible
Your existing integrations with regular session tokens continue to work. You can adopt secure tokens gradually for high-risk actions without migrating everything at once.

Device session tokens are JWTs. On your backend, verify the token signature and validate the expiration (`exp`) claim (for secure tokens).

## Obtain session token

The session token links your backend API calls to the device session. When you trigger action events (such as a login or transaction attempt) from the backend using [API calls](/openapi/risk/client-actions.openapi/other/triggeranaction), Mosaic needs the token to associate the action with the device. A session token is not required when triggering events directly from the SDK.

Your client obtains the token from the SDK and passes it to the backend. To obtain a device session token:

1. Initialize the SDK with `enableSessionToken: true` (see [initialization instructions](/guides/risk/quick_start_backendapi#step-2-start-an-sdk-session)).
2. Call `getSessionToken()` or `getSecureSessionToken()` depending on the token type you need.


Regular device session token
##### 

Request regular device session token by calling [getSessionToken()](/sdk-ref/platform/modules/drs/#getsessiontoken) SDK method.  It returns the current device session token as a string (`session_token`).

JavaScript

```js
// Request regular device session token
const sessionToken = await drs.getSessionToken();
```

Kotlin

```kotlin
TSAccountProtection.getSessionToken(object : ISessionTokenCallback {
    override fun onSessionToken(sessionToken: String) {

    }
})
```

Swift

```swift
TSAccountProtection.getSessionToken { token in
    debugPrint("[DEBUG]: Fraud Prevention device session token: \(token)")
}
```

Secure device session token
##### 

Request a secure device session token by calling [getSecureSessionToken()](/sdk-ref/platform/modules/drs#getsecuresessiontoken) for high-risk scenarios requiring action binding.

The method accepts two optional parameters:

- `actionType` (string, default: null): Binds the token to a specific action type (for example, `"transaction"` or `"login"`).
- `expirationSeconds` (number, default: 300): Sets the validity period of the token in seconds (max: 3600).


Request the secure session token at the moment the user initiates the sensitive action (for example, when they click **Login** or **Confirm transaction**). Always use a token that matches the action type: for each sensitive action (for example, a transaction or `account_details_change` after a login), call `getSecureSessionToken()` again with the action type for that operation. Using a secure session token bound to a different action causes the request to fail with the 403 "Action type mismatch" error.

Note
Currently, secure device session tokens can be requested via the Web SDK only.


```js
  // Request secure device session token with additional params
  const secureSessionToken = await drs.getSecureSessionToken("login", 600);
```

The backend includes the token in the API request when calling [Trigger an action](/openapi/risk/client-actions.openapi/other/triggeranaction).

For complete implementation details, see the [Backend integration guide](/guides/risk/quick_start_backendapi).

## Recommendations and device sessions

Obtaining recommendations isn’t tied to a specific device session. Depending on your business flows, it can occur immediately after triggering action events (e.g., for real-time assessment of high-risk actions) or asynchronously (e.g., in monitoring mode with manual risk review procedures).