<!-- llms.txt: https://workos.com/llms.txt -->

# Radar Integration Guide

## Introduction

[Radar](https://workos.com/docs/authkit/radar) adds automated fraud and bot protection to your authentication flows. If you use AuthKit's Hosted UI, Radar is built in and requires no additional integration. For applications that use the User Management APIs directly or have a custom authentication stack, additional integration is required.

This guide covers two integration paths:

- **Radar in the User Management APIs** — for applications that call the WorkOS [Authentication API](https://workos.com/docs/reference/authkit/authentication) directly (headless AuthKit).
- **Standalone Radar** — for applications with a fully custom authentication system that want to leverage Radar's risk engine independently.

> Radar in the User Management APIs and Standalone Radar are currently in preview. [Contact support](mailto:support@workos.com) or reach out in your shared Slack channel to get access.

***

## When to use each mode

| Integration path | When to use |
| --- | --- |
| **Hosted AuthKit** | You use AuthKit's Hosted UI. Radar is built in — no extra work needed. See the [Radar overview](https://workos.com/docs/authkit/radar). |
| **User Management APIs** | You call the WorkOS [Authentication API](https://workos.com/docs/reference/authkit/authentication) directly to build your own sign-in and sign-up UI, and you want Radar to protect those flows. |
| **Standalone Radar** | You have your own authentication system and don't use WorkOS for authentication, but want to use Radar's risk engine to evaluate sign-in and sign-up attempts. |

***

## Client signals library

The [`@workos/radar-signals`](https://www.npmjs.com/package/@workos/radar-signals) package collects browser signals (device fingerprint, bot detection, and more) and returns a correlation token. Pass this token server-side with your authentication calls so Radar can make informed risk decisions.

```bash
npm install @workos/radar-signals
```

### React

Wrap your authentication UI in `RadarSignalsProvider`. Signal collection starts automatically on mount. Find your client ID in the [WorkOS dashboard](https://dashboard.workos.com) under **Applications**.

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

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

Call `getToken()` from any child component to retrieve the correlation token:

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

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

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const signalsToken = await getToken();

    // Pass signalsToken to your backend, then include it
    // as signalsId in your WorkOS API calls
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* your form fields */}
      <button type="submit" disabled={!tokenReady}>
        Sign in
      </button>
    </form>
  );
}
```

### Vanilla JavaScript

If you're not using React, use the `WorkOSRadar` class directly:

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

const radar = WorkOSRadar.init({ clientId: 'client_01ABC...' });
const signalsToken = await radar.getToken();
```

***

## Radar in the User Management APIs

When using the User Management APIs, pass the user's IP address, user agent, and the signals token (from the client signals library) with your authentication calls. Radar evaluates each attempt and may return a block or challenge error that your application needs to handle.

> **Note:** Once Radar in the User Management APIs is enabled for your environment, it starts in **log mode** — Radar evaluates every request and records decisions, but does not enforce them. This lets you complete your integration and observe Radar's behavior before it affects users. When you're ready, enable enforcement from the [Radar configuration page](https://dashboard.workos.com/environment/radar/configuration) in the WorkOS dashboard to start returning challenges and blocks.

### Key parameters

| Parameter | Description |
| --- | --- |
| `ip_address` | The end user's IP address. Make sure to forward the true client IP, not your server's address. |
| `user_agent` | The end user's browser user agent string. |
| `signals_id` | The correlation token from `@workos/radar-signals`. Links client-side signals to the server-side authentication attempt. |
| `radar_auth_attempt_id` | Returned when creating a user or Magic Auth session. Thread this into the subsequent authenticate call so Radar correlates the full flow. |
| `pending_authentication_token` | Returned in challenge errors. Used to complete Radar email or SMS challenges. |

### Password

#### Sign up

When signing up a user with email and password, pass Radar parameters to both the create user and authenticate calls. Thread the `radar_auth_attempt_id` from the user creation response into the authentication call.

#### Sign in

For sign-in, pass the signals token directly to the authentication call. No `radar_auth_attempt_id` is needed since there's no preceding user creation step.

### Magic Auth

Pass Radar parameters when creating the Magic Auth session and thread the `radar_auth_attempt_id` into the subsequent authenticate call. The same flow applies to both sign-up and sign-in with Magic Auth.

### OAuth and SSO

For OAuth and SSO flows, pass Radar parameters when exchanging the authorization code.

***

## Handling Radar challenges

When Radar flags an authentication attempt as suspicious, the API returns a challenge error instead of completing the authentication. Your application needs to handle these errors and guide the user through the verification step.

### Email challenges

When Radar issues an email challenge, WorkOS sends a one-time code to the user's email address. The error response includes a `pending_authentication_token` and a `radar_challenge_id`. Use these along with the code the user enters to complete authentication.

See the [Radar email challenge error](https://workos.com/docs/reference/authkit/authentication-errors/radar-email-challenge-error) and [authenticate with Radar email challenge](https://workos.com/docs/reference/authkit/authentication/radar-email-challenge) API reference for details.

### SMS challenges

SMS challenges require the user to verify a phone number. The error response includes a `pending_authentication_token`. First send the SMS code, then complete authentication with the code the user enters.

> SMS challenges must be enabled separately. You can enable them from the Policies section of the [Radar configuration page](https://dashboard.workos.com/environment/radar/configuration) in the WorkOS dashboard.

See the [Radar SMS challenge error](https://workos.com/docs/reference/authkit/authentication-errors/radar-sms-challenge-error), [send a Radar SMS challenge](https://workos.com/docs/reference/authkit/send-radar-sms-challenge), and [authenticate with Radar SMS challenge](https://workos.com/docs/reference/authkit/authentication/radar-sms-challenge) API reference for details.

### Block errors

When Radar blocks an authentication attempt entirely, the API returns an error with the code `policy_denied`. Your application should display an appropriate message to the user indicating that the sign-in was not successful.

***

## Standalone Radar

Standalone Radar allows applications with custom authentication systems to use Radar's risk engine independently. Instead of Radar evaluating risk automatically during WorkOS authentication flows, your application submits authentication attempts directly to the [Radar attempts API](https://workos.com/docs/reference/radar/attempts) and receives a verdict.

### Creating an attempt

Submit an authentication attempt to Radar for evaluation. The response includes a `verdict` (`allow`, `block`, or `challenge`) and a `reason`.

### Updating an attempt

After the authentication attempt completes in your system, update the Radar attempt with the outcome so Radar can refine its risk models.

See the [Radar attempts API reference](https://workos.com/docs/reference/radar/attempts) for the full list of parameters.

***

## Going live

Radar starts in **log mode** when either Radar in the User Management APIs or the Standalone Radar API is enabled for your environment. In log mode, Radar evaluates every authentication request and records its decisions, but doesn't enforce them — all requests are allowed through. This gives you time to integrate Radar into your code and verify that everything is wired up correctly.

Once you've confirmed that Radar signals are flowing and decisions look correct in the [Radar dashboard](https://dashboard.workos.com/environment/radar), enable enforcement from the [Radar configuration page](https://dashboard.workos.com/environment/radar/configuration). At that point, Radar will begin returning challenges and blocks to your application.

**Recommended steps:**

1. [Contact support](mailto:support@workos.com) or reach out in your shared Slack channel to enable Radar in the User Management APIs or the Standalone Radar API for your environment.
2. Complete your client-side and server-side integration using this guide.
3. Deploy your changes and verify that Radar decisions appear in the dashboard.
4. Review Radar's logged decisions to make sure they match your expectations.
5. Enable enforcement when you're confident in the integration.

***

## Related resources

- [Radar overview](https://workos.com/docs/authkit/radar) — dashboard, detections, configuration, managed lists, and custom restrictions
- [Authentication API reference](https://workos.com/docs/reference/authkit/authentication) — password, Magic Auth, OAuth/SSO authenticate endpoints
- [Radar email challenge](https://workos.com/docs/reference/authkit/authentication/radar-email-challenge) — complete an email challenge
- [Radar SMS challenge](https://workos.com/docs/reference/authkit/authentication/radar-sms-challenge) — complete an SMS challenge
- [Send a Radar SMS challenge](https://workos.com/docs/reference/authkit/send-radar-sms-challenge) — send an SMS verification code
- [Radar attempts API](https://workos.com/docs/reference/radar/attempts) — Standalone Radar risk assessment
- [`@workos/radar-signals` on npm](https://www.npmjs.com/package/@workos/radar-signals) — client signals library