Backend API quick start

This article describes how to implement Detection and Response services in your web application using a backend API approach. Initially, you need to install and initialize Mosaic's Platform web SDK in your front-end application. This SDK is responsible for collecting and streaming 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.

How it works

The flow starts with the user navigating to the webpage (1). The SDK gets initialized and starts streaming 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 reports an 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).

Step 1: Get client credentials

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

1. From Applications , click Add application .
2. Add the friendly application name to display in the Admin Portal.
3. Add a client display name, and your website URL as a redirect URI (e.g., https://your-domain.com ).

   Note

   These fields are required for all Mosaic apps, but won’t be used for Detection and Response.

4. Click Add to create your application. This will automatically generate your client credentials.

Step 2: Start an SDK session

To detect risk and generate recommendations, DRS services rely 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.

Start monitoring your end-user risk levels by loading the SDK. To do this, add the code below to your front-end web application by including the following HTML script tag in all relevant pages. The [CLIENT_ID] should be replaced with your client ID, created with the credentials in step 1.

// Loads the latest SDK version within the major version 1
// See changelog for details and update version if necessary
<script src="https://platform-websdk.transmitsecurity.io/platform-websdk/1.x/ts-platform-websdk.js" defer="true" id="ts-platform-script"></script>

You also need to initialize and configure the SDK by adding the HTML script tag below in all relevant pages. Upon initialization, the SDK generates a session token, which should be passed to your backend as it will later be used to link your backend calls to the browser session.

<script>
  document.getElementById("ts-platform-script").addEventListener("load", async function() {
  await window.tsPlatform.initialize({ clientId: "[CLIENT_ID]", drs: { enableSessionToken: true } });
  // Retrieves session token required for backend API calls
  const sessionToken = await window.tsPlatform.drs.getSessionToken();
});
</script>

For the complete documentation about the web SDK, visit our Platform web SDK documentation.

Step 3: Get access token

Mosaic APIs are authorized using an OAuth access token so you'll need to fetch a token using your client credentials (from step 1). The token should target the following resource: https://risk.identity.security. To do this, send the following request:

  const { access_token } = 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],
        resource: 'https://risk.identity.security'
      })
    }
  );

Step 4: Report actions

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. Replace [ACTION_TYPE] with the appropriate action type from our list of actions. To improve detection and response, pass the correlation ID as well (optional). This API returns an action_token to be used in the next step to fetch a recommendation.

Here is an example:

import fetch from 'node-fetch';

async function run() {
  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]', // Session token generated by SDK in step 2
        action_type: '[ACTION_TYPE]',
        correlation_id: '[CORRELATION_ID]' // Optional
      })
    }
  );

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

run();

Step 5: Fetch recommendation

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.

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
    },
  }
);

Step 6: Report action result

Report the action outcome back to Mosaic to enrich the risk profile. By reporting the action result, you help improve risk detection algorithms, that especially makes sense for "challenge" recommendations. For example, in Step 5 Mosaic returned "challenge" recommendation, and your application asked a user to authenticate with SMS OTP which they successfully did. This could a sign of a legitimate action.

Along with the action result, a user identifier can be reported to Mosaic to set the user for all subsequent events in the browser session, provided that you've fully authenticated the user (including, for example, any required 2FA that was done). Note that the user identifier should be an opaque identifier for the user in your system. This must not include personal user identifiers, such as email.

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. If provided, sets the user
        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();