Backend API quick start

This article describes how to implement Fraud Prevention in your application using a backend API approach. Initially, you need to install and initialize the relevant Mosaic's SDK (for Web, Android, iOS, React Native, Flutter, or Cordova) in order to collect and stream telemetry data to Mosaic. The backend API then processes this data and responds accordingly, reporting specific user actions to Mosaic and fetching risk assessment recommendations for those actions.

The flow starts with the user navigating to the webpage or app (1). The SDK gets initialized, obtains a device session token, and starts sending telemetry to Mosaic (2). When a user performs an action, for example, clicks a login button (3), your client passes this information to your backend (4) and the backend triggers an action event to Mosaic (5). Having received an action token (6), the application backend uses it to fetch recommendation from Mosaic (7 & 8) and instructs the client to act accordingly (9) in order to complete the login procedure (10). As a last step, your server can report the action result back to Mosaic and set the user (11).

Ensure that Fraud Prevention is enabled as the risk engine for your tenant. Identity Threat Protection and Fraud Prevention are mutually exclusive—contact your Customer Success Manager to enable the appropriate engine.

Client credentials are used to identify your app and generate access tokens for authorizing Mosaic requests. To obtain them, you'll need to create an application in the Admin Portal (if you don't have one yet).

From Applications, click Add application and enter the friendly application name to display in the Admin Portal.

Then open the application's Clients tab and add an OIDC-based User authentication client for this integration. Select Web app or Native app according to the client that initializes the SDK, keep Client Secret as the authentication method, and, if prompted, enter a redirect URI. Upon saving the client, Mosaic automatically generates the Client ID and Client Secret.

To detect risk and generate recommendations, Fraud Prevention relies on the analysis of telemetry data, which includes details about user interactions, journeys, and device information. To transfer this data to Mosaic, you need to use Mosaic's client-side SDK. Upon initialization, the SDK automatically tracks telemetry data and streams it to Mosaic.

Initializing the SDK creates a session on a device. Request a session token, for example using getSessionToken() (Web, Android, iOS, React Native, Flutter, or Cordova) or getSecureSessionToken() (Web) calls. Then pass it to your backend as it will later be used to link your backend calls to the session. To learn more about session tokens, see How device sessions work. Note that session tokens have a short lifespan and shouldn't be cached.

import { drs, initialize } from '@transmitsecurity/platform-web-sdk';

// Initialize the SDK with your client ID and DRS configuration.
// If SDK was loaded via script tag, use: window.tsPlatform.initialize({...})
await initialize({
  clientId: '[CLIENT_ID]', // Client ID from the app > client settings in the Admin Portal
  drs: {
    enableSessionToken: true,
    serverPath: 'https://api.transmitsecurity.io/risk-collect/' // Required: Set serverPath based on your region or custom domain
  }
});

// Retrieves a session token required for backend API calls
const sessionToken = await drs.getSessionToken();

// For enhanced security, use secured session token (recommended for high-risk actions)
const securedSessionToken = await drs.getSecureSessionToken("login", 600);

Mosaic APIs are authorized using an OAuth access token so you'll need to fetch a token using your client credentials (from step 1). To do this, send the following request:

  const resp = await fetch(
    `https://api.transmitsecurity.io/oidc/token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: '[CLIENT_ID]',
        client_secret: '[CLIENT_SECRET]'
      })
    }
  );
  const { access_token } = await resp.json();

To obtain risk recommendations for sensitive actions, your application should report these actions using a backend API. To do this, send a POST request to /action/trigger-action like the one below when a user requests to perform the action.

The request must include either a session token or a secure session token obtained in Step 3. Replace [ACTION_TYPE] with the appropriate action type from our list of actions. If using a secure session token, make sure it matches the action type. Using a secure session token bound to a different action causes the request to fail with the 403 "Action type mismatch" error.

To improve Fraud Prevention, pass the correlation ID, claimed user ID and its type (optional). This API returns an action_token to be used in the next step to fetch a recommendation.

If the user completed login outside the current Fraud Prevention flow before this action, for example on a different site or through an external identity provider, include the auth_context field with the required user_id instead of claimed_user_id. auth_context doesn't infer or verify the user's identity: your backend must already know the fully authenticated user. This sets the user for the device session in the same call and can optionally report how the user authenticated, without waiting to report a user_id in Step 6.

For details, see Associate users with risk actions.

Here is an example:

import fetch from 'node-fetch';

async function run() {

  const query = new URLSearchParams({
    get_recommendation: 'false' // Default. Set to true to return the recommendation and skip Step 5
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/risk/v1/action/trigger-action`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer [ACCESS_TOKEN]' // Access token generated in Step 3
      },
      body: JSON.stringify({
        session_token: '[SESSION_TOKEN]', // device session token generated by SDK in Step 2
        // Alternatively, use secure session token matching the action type
        // secured_session_token: '[SECURE_SESSION_TOKEN]'
        action_type: '[ACTION_TYPE]', // For example, login
        correlation_id: '[CORRELATION_ID]', // Optional
        claimed_user_id: '[CLAIMED_USER_ID]', // Optional
        claimed_user_id_type: 'email', // Optional

        // For an already-authenticated user, replace the claimed user fields above with:
        // auth_context: {
        //   user_id: '[USER_ID]', // Required: the already-authenticated user
        //   login_timestamp: 1767225600000, // Optional: Unix timestamp in ms
        //   auth_method_type: 'password', // Optional
        //   challenge_type: 'sms_otp', // Optional
        //   failed_attempts: 1, // Optional
        //   login_origin: 'https://example.com/login' // Optional
        // }
      })
    }
  );

  const data = await resp.json();
  console.log(data);
}

run();

You can fetch recommendations for the reported action from your backend. To do this, invoke the Recommendation API by sending a request like the one below. Replace [ACTION_TOKEN] with the token returned in Step 4.

const query = new URLSearchParams({
  action_token: '[ACTION_TOKEN]', // Action token returned in step 4
}).toString();

const resp = await fetch(
  `https://api.transmitsecurity.io/risk/v1/recommendation?${query}`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer [ACCESS_TOKEN]', // Access token generated in step 3
    },
  }
);

Report the action outcome back to Mosaic to enrich the risk profile. This is especially useful for challenge recommendations. For example, if Step 5 returned a challenge recommendation and your application asked the user to authenticate with SMS OTP, reporting a successful result helps Mosaic learn that the action was legitimate.

import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    `https://api.transmitsecurity.io/risk/v1/action/result`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer [ACCESS_TOKEN]', // Access token generated in step 3
      },
      body: JSON.stringify({
        action_token: '[ACTION_TOKEN]', // Action token returned in step 4
        result: '[RESULT]', // Result of action. One of success, failure, or incomplete
        user_id: '[USER_ID]', // Optional. Include on successful authentication when Step 4 didn't already set the user via auth_context
        challenge_type: '[CHALLENGE]' // Optional. Specify the type of challenge performed such as passkey or sms_otp
      })
    }
  );

  const data = await resp.json();
  console.log(data);
}

run();

The user gets automatically cleared in the following cases:

• Once a device session expires
• Triggering a new login action
• Reporting a different user ID for an event
• Calling clearUser() from the client side