JavaScript SDK quick start

This guide describes how to quickly integrate account protection into your Web application to get started. This includes both the client-side integration, as well as the backend API integration required to complete the flow.

Step 1: Get client credentials

To integrate with Transmit Security, you'll need to obtain your client credentials from the Admin Portal. From Risk > Settings, you can obtain your client ID and client secret. These will be used to identify your app and generate authorization for requests to Transmit.

Step 2: Load SDK

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 from step 1.

Copy
Copied
<script src="https://cdn.riskid.security/sdk/web_sdk_latest.js" defer="true" />

You also need to initialize and configure the SDK by adding the following HTML script tag in all relevant pages:

Copy
Copied
<script>
  document.addEventListener("TSAccountProtectionReady", function(e) {
    window.myTSAccountProtection = new TSAccountProtection("[CLIENT_ID]");
    window.myTSAccountProtection.init();
  });
</script>

Step 3: Set user

A user identifier must be reported to Transmit Security after you've fully authenticated the user (including, for example, any required 2FA that was done). This will set the user for all subsequent events in the browser session.

To do this, add the JS code below after your application has authenticated a user (or after SDK initialization if you already have the user context of the authenticated user when loading the page). The [USER_ID] is an opaque identifier for the user in your system.

Copy
Copied
myTSAccountProtection.setAuthenticatedUser('[USER_ID]');
Note:

This must not include personal user identifiers, such as email.

Step 4: Report actions

To obtain risk recommendations for sensitive actions, your application should report these actions using the SDK. To do this, add the JS code below to relevant user interactions (such as the Login button click event handler). The [ACTION_TYPE] can be either login, register, transaction, password_reset, logout, checkout, account_details_change, account_auth_change, withdraw or credits_change.

Copy
Copied
myTSAccountProtection.triggerActionEvent("[ACTION_TYPE]").then((actionResponse) => {
  let actionToken = actionResponse.actionToken;
  // Add code here to send the action and the received actionToken to your backend
});
Note:

Make sure to pass the received actionToken to your backend along with the actual action invocation to ensure you can leverage the recommendation in the next step.

Step 5: Fetch recommendation

You can fetch recommendations for the reported action using the Recommendation API. This is the same API that's also used for mobile integrations.

Transmit Security 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:

Copy
Copied
  const { access_token } = await fetch(
    `https://api.riskid.security/v1/oauth/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],
        scope: 'riskid.recommendation.fetch'
      })
    }
  );

From your backend, invoke the Recommendation API by sending a request like the one below. The [ACCESS_TOKEN] is the authorization token you obtained using your client credentials and [ACTION_TOKEN] is the actionToken received from the SDK in step 4.

Copy
Copied
const query = new URLSearchParams({
  action_token: '[ACTION_TOKEN]',
}).toString();

const resp = await fetch(
  `https://api.riskid.security/v1/recommendation?${query}`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer [ACCESS_TOKEN]',
    },
  }
);

Step 6: Report recommendation outcome

Account protection leverages heuristics and machine learning (ML) models to make sure you're getting the best recommendations at all times. To allow us to fine tune your recommendation models, we need insights on the results of challenges you've performed based on our recommendation. This should be provided by sending a backend API request once the challenge is completed (either successfully or with a failure).

Details Coming Soon

Step 7: Clear user

After the user logs out or the user session expires, you should clear the set user so they are not associated with future actions. To clear the user, call the clearUser() method:

Copy
Copied
myTSAccountProtection.clearUser();