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.
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.
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: truewhen initializing the SDK.
For more information on maintaining user identity, see this guide.
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 the action it was created for 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.
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).
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, 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:
- Initialize the SDK with
enableSessionToken: true(see initialization instructions). - Call
getSessionToken()orgetSecureSessionToken()depending on the token type you need.
Request regular device session token by calling getSessionToken() SDK method. It returns the current device session token as a string (session_token).
// Request regular device session token
const sessionToken = await drs.getSessionToken();The backend includes the token in the API request when calling Trigger an action.
For complete implementation details, see the Backend integration guide.
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).