@workos/radar-signals

Collect browser signals for WorkOS Radar fraud and bot detection.

@workos/radar-signals runs in the browser, loads a signal collection script from the WorkOS CDN, and returns a correlation token you pass with your authentication calls. WorkOS Radar uses these signals server-side to evaluate risk.

Installation

npm install @workos/radar-signals

Quick start

Wrap your app (or auth subtree) in RadarSignalsProvider. Signal collection starts automatically on mount. You can find your client ID in the WorkOS Dashboard under Applications.

import { RadarSignalsProvider } from '@workos/radar-signals/react';

function App() {
  return (
    <RadarSignalsProvider clientId="client_01ABC...">
      <LoginForm />
    </RadarSignalsProvider>
  );
}

Then call getToken() from any child component when you need the correlation token:

import { useRadarToken } from '@workos/radar-signals/react';

function LoginForm() {
  const { getToken, tokenReady } = useRadarToken();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const token = await getToken();
    await fetch('/api/auth/login', {
      method: 'POST',
      body: JSON.stringify({ radar_token: token }),
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* ... */}
      <button type="submit" disabled={!tokenReady}>Log in</button>
    </form>
  );
}

How it works

1. The library loads a signal collection script from the WorkOS CDN
2. The CDN script collects device and environment signals and submits them to the WorkOS API
3. getToken() returns the correlation token — if collection is still in-flight, it waits for completion
4. Pass the token server-side to WorkOS Radar for risk evaluation

The library is fail-open: getToken() always returns a value, even if the CDN script fails to load. Server-side Radar handles missing signals gracefully.

React API

Requires React 18 or later. Import from @workos/radar-signals/react.

<RadarSignalsProvider>

Initializes Radar and provides the token to descendant components via context.

Prop	Type	Required	Description
clientId	string	Yes	Your WorkOS client ID (publishable, safe for browser use). Find this in the WorkOS Dashboard under Applications.
apiUrl	string	No	Your custom Auth API domain, e.g. https://auth.example.com. Signals are posted to this origin instead of api.workos.com, so your CSP connect-src must allow it (the script itself still loads from https://js.workos.com). Must be https://; otherwise signals go to https://api.workos.com (the default).

useRadarToken()

Returns { getToken, tokenReady } from the nearest RadarSignalsProvider.

• getToken() — returns the token after collection completes (async)
• tokenReady — true once a real token is available; useful for disabling submit buttons until signals are collected

useRadarSignals(options)

Standalone hook that creates its own Radar instance — no provider needed. Accepts the same options as RadarSignalsProvider. Returns { getToken, tokenReady }.

import { useRadarSignals } from '@workos/radar-signals/react';

function LoginForm() {
  const { getToken, tokenReady } = useRadarSignals({
    clientId: 'client_01ABC...',
  });
  // ...
}

Vanilla JS

If you're not using React, the WorkOSRadar class provides the same functionality.

import { WorkOSRadar } from '@workos/radar-signals';

const radar = WorkOSRadar.init({ clientId: 'client_01ABC...' });

const token = await radar.getToken();

WorkOSRadar.init(options)

Creates a new Radar instance and loads the CDN collectors script.

Option	Type	Required	Description
clientId	string	Yes	Your WorkOS client ID (publishable, safe for browser use). Find this in the WorkOS Dashboard under Applications.
apiUrl	string	No	Your custom Auth API domain, e.g. https://auth.example.com. Signals are posted to this origin instead of api.workos.com, so your CSP connect-src must allow it (the script itself still loads from https://js.workos.com). Must be https://; otherwise signals go to https://api.workos.com (the default).

radar.getToken()

Returns the correlation token after signals have been collected and submitted. If the CDN script is still loading, the promise resolves once complete.

radar.tokenReady

Boolean flag that becomes true once a real token is available. Useful for checking whether collection has completed without awaiting.

Script tag usage

For environments without a bundler, load the IIFE build via a <script> tag.

<script src="https://unpkg.com/@workos/radar-signals/dist/workos-radar-signals.global.js"></script>
<script>
  var radar = WorkOSRadar.init({ clientId: 'client_01ABC...' });
  radar.getToken().then(function (token) {
    // pass token with your auth request
  });
</script>

License

MIT