Radar Integration Guide

Integrate Radar fraud and bot detection with the User Management APIs or Standalone Radar API.

Introduction

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 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 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.
User Management APIs	You call the WorkOS Authentication API 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 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.

 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 under Applications.

 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:

 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:

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

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

Script tag

For environments without a build tool, load the library 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 to your backend
  });
</script>

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.

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

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.

JavaScript

 # 1. Create the user
curl --request POST \
  --url https://api.workos.com/user_management/users \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "email": "marcelina@example.com",
    "password": "i8uv6g34kd490s",
    "ip_address": "210.123.170.80",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "signals_id": "signals_token_value"
  }
BODY
# Response includes radar_auth_attempt_id

# 2. Authenticate, threading the Radar attempt ID from step 1
curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "password",
    "email": "marcelina@example.com",
    "password": "i8uv6g34kd490s",
    "ip_address": "210.123.170.80",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "radar_auth_attempt_id": "radar_auth_attempt_id_from_step_1"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

// 1. Create the user and capture the Radar attempt ID
const user = await workos.userManagement.createUser({
  email: 'marcelina@example.com',
  password: 'i8uv6g34kd490s',
  ipAddress: '210.123.170.80',
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  signalsId: signalsToken,
});

// 2. Authenticate, threading the Radar attempt ID from step 1
const auth = await workos.userManagement.authenticateWithPassword({
  clientId: 'client_123456789',
  email: 'marcelina@example.com',
  password: 'i8uv6g34kd490s',
  ipAddress: '210.123.170.80',
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  radarAuthAttemptId: user.radarAuthAttemptId,
});

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

# 1. Create the user and capture the Radar attempt ID
user = WorkOS.client.user_management.create_user(
  email: "marcelina@example.com",
  password: "i8uv6g34kd490s",
  ip_address: "210.123.170.80",
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  signals_id: signals_token
)

# 2. Authenticate, threading the Radar attempt ID from step 1
auth = WorkOS.client.user_management.authenticate_with_password(
  client_id: "client_123456789",
  email: "marcelina@example.com",
  password: "i8uv6g34kd490s",
  ip_address: "210.123.170.80",
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  radar_auth_attempt_id: user.radar_auth_attempt_id
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

# 1. Create the user and capture the Radar attempt ID
user = client.user_management.create_user(
    email="marcelina@example.com",
    password="i8uv6g34kd490s",
    ip_address="210.123.170.80",
    user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    signals_id="signals_token_value",
)

# 2. Authenticate, threading the Radar attempt ID from step 1
auth = client.user_management.authenticate_with_password(
    email="marcelina@example.com",
    password="i8uv6g34kd490s",
    ip_address="210.123.170.80",
    user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    radar_auth_attempt_id=user.radar_auth_attempt_id,
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	// 1. Create the user and capture the Radar attempt ID
	user, err := client.UserManagement().Create(context.Background(), &workos.UserManagementCreateParams{
		Email:     "marcelina@example.com",
		Password:  "i8uv6g34kd490s",
		IPAddress: "210.123.170.80",
		UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
		SignalsID: signalsToken,
	})
	if err != nil {
		panic(err)
	}

	// 2. Authenticate, threading the Radar attempt ID from step 1
	auth, err := client.UserManagement().AuthenticateWithPassword(context.Background(), &workos.UserManagementAuthenticateWithPasswordParams{
		ClientID:           "client_123456789",
		Email:              "marcelina@example.com",
		Password:           "i8uv6g34kd490s",
		IPAddress:          "210.123.170.80",
		UserAgent:          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
		RadarAuthAttemptID: user.RadarAuthAttemptID,
	})
	if err != nil {
		panic(err)
	}

	_ = auth
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

// 1. Create the user and capture the Radar attempt ID
$user = $workos
    ->userManagement()
    ->createUser(
        email: "marcelina@example.com",
        password: "i8uv6g34kd490s",
        ipAddress: "210.123.170.80",
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        signalsId: $signalsToken,
    );

// 2. Authenticate, threading the Radar attempt ID from step 1
$auth = $workos
    ->userManagement()
    ->authenticateWithPassword(
        email: "marcelina@example.com",
        password: "i8uv6g34kd490s",
        ipAddress: "210.123.170.80",
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        radarAuthAttemptId: $user->radarAuthAttemptId,
    );

 import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.AuthenticateWithPasswordOptions;
import com.workos.usermanagement.UserManagementApi.CreateUserOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

// 1. Create the user and capture the Radar attempt ID
CreateUserOptions createOptions =
    CreateUserOptions.builder()
        .email("marcelina@example.com")
        .password("i8uv6g34kd490s")
        .ipAddress("210.123.170.80")
        .userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36")
        .signalsId(signalsToken)
        .build();

var user = workos.userManagement.createUser(createOptions);

// 2. Authenticate, threading the Radar attempt ID from step 1
AuthenticateWithPasswordOptions authOptions =
    AuthenticateWithPasswordOptions.builder()
        .email("marcelina@example.com")
        .password("i8uv6g34kd490s")
        .ipAddress("210.123.170.80")
        .userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36")
        .radarAuthAttemptId(user.getRadarAuthAttemptId())
        .build();

workos.userManagement.authenticateWithPassword(authOptions);

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.

JavaScript

 # 1. Create the Magic Auth session
curl --request POST \
  --url https://api.workos.com/user_management/magic_auth \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "email": "marcelina@example.com",
    "ip_address": "210.123.170.80",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "signals_id": "signals_token_value"
  }
BODY
# Response includes radar_auth_attempt_id

# User receives a one-time code via email...

# 2. Authenticate, threading the Radar attempt ID from step 1
curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "urn:workos:oauth:grant-type:magic-auth:code",
    "email": "marcelina@example.com",
    "code": "123456",
    "ip_address": "210.123.170.80",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "radar_auth_attempt_id": "radar_auth_attempt_id_from_step_1"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

// 1. Create the Magic Auth session and capture the Radar attempt ID
const magicAuth = await workos.userManagement.createMagicAuth({
  email: 'marcelina@example.com',
  ipAddress: '210.123.170.80',
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  signalsId: signalsToken,
});

// User receives a one-time code via email...

// 2. Authenticate, threading the Radar attempt ID from step 1
const auth = await workos.userManagement.authenticateWithMagicAuth({
  clientId: 'client_123456789',
  email: 'marcelina@example.com',
  code: userEnteredCode,
  ipAddress: '210.123.170.80',
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  radarAuthAttemptId: magicAuth.radarAuthAttemptId,
});

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

# 1. Create the Magic Auth session and capture the Radar attempt ID
magic_auth = WorkOS.client.user_management.create_magic_auth(
  email: "marcelina@example.com",
  ip_address: "210.123.170.80",
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  signals_id: signals_token
)

# User receives a one-time code via email...

# 2. Authenticate, threading the Radar attempt ID from step 1
auth = WorkOS.client.user_management.authenticate_with_magic_auth(
  client_id: "client_123456789",
  email: "marcelina@example.com",
  code: user_entered_code,
  ip_address: "210.123.170.80",
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  radar_auth_attempt_id: magic_auth.radar_auth_attempt_id
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

# 1. Create the Magic Auth session and capture the Radar attempt ID
magic_auth = client.user_management.create_magic_auth(
    email="marcelina@example.com",
    ip_address="210.123.170.80",
    user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    signals_id="signals_token_value",
)

# User receives a one-time code via email...

# 2. Authenticate, threading the Radar attempt ID from step 1
auth = client.user_management.authenticate_with_magic_auth(
    email="marcelina@example.com",
    code="123456",
    ip_address="210.123.170.80",
    user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    radar_auth_attempt_id=magic_auth.radar_auth_attempt_id,
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	// 1. Create the Magic Auth session and capture the Radar attempt ID
	magicAuth, err := client.UserManagement().CreateMagicAuth(context.Background(), &workos.UserManagementCreateMagicAuthParams{
		Email:     "marcelina@example.com",
		IPAddress: "210.123.170.80",
		UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
		SignalsID: signalsToken,
	})
	if err != nil {
		panic(err)
	}

	// User receives a one-time code via email...

	// 2. Authenticate, threading the Radar attempt ID from step 1
	auth, err := client.UserManagement().AuthenticateWithMagicAuth(context.Background(), &workos.UserManagementAuthenticateWithMagicAuthParams{
		ClientID:           "client_123456789",
		Email:              "marcelina@example.com",
		Code:               userEnteredCode,
		IPAddress:          "210.123.170.80",
		UserAgent:          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
		RadarAuthAttemptID: magicAuth.RadarAuthAttemptID,
	})
	if err != nil {
		panic(err)
	}

	_ = auth
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

// 1. Create the Magic Auth session and capture the Radar attempt ID
$magicAuth = $workos
    ->userManagement()
    ->createMagicAuth(
        email: "marcelina@example.com",
        ipAddress: "210.123.170.80",
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        signalsId: $signalsToken,
    );

// User receives a one-time code via email...

// 2. Authenticate, threading the Radar attempt ID from step 1
$auth = $workos
    ->userManagement()
    ->authenticateWithMagicAuth(
        email: "marcelina@example.com",
        code: $userEnteredCode,
        ipAddress: "210.123.170.80",
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        radarAuthAttemptId: $magicAuth->radarAuthAttemptId,
    );

 import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.AuthenticateWithMagicAuthOptions;
import com.workos.usermanagement.UserManagementApi.CreateMagicAuthOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

// 1. Create the Magic Auth session and capture the Radar attempt ID
CreateMagicAuthOptions createOptions =
    CreateMagicAuthOptions.builder()
        .email("marcelina@example.com")
        .ipAddress("210.123.170.80")
        .userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36")
        .signalsId(signalsToken)
        .build();

var magicAuth = workos.userManagement.createMagicAuth(createOptions);

// User receives a one-time code via email...

// 2. Authenticate, threading the Radar attempt ID from step 1
AuthenticateWithMagicAuthOptions authOptions =
    AuthenticateWithMagicAuthOptions.builder()
        .email("marcelina@example.com")
        .code(userEnteredCode)
        .ipAddress("210.123.170.80")
        .userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36")
        .radarAuthAttemptId(magicAuth.getRadarAuthAttemptId())
        .build();

workos.userManagement.authenticateWithMagicAuth(authOptions);

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.

JavaScript

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "password",
    "email": "marcelina@example.com",
    "password": "i8uv6g34kd490s",
    "ip_address": "210.123.170.80",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "signals_id": "signals_token_value"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const auth = await workos.userManagement.authenticateWithPassword({
  clientId: 'client_123456789',
  email: 'marcelina@example.com',
  password: 'i8uv6g34kd490s',
  ipAddress: '210.123.170.80',
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  signalsId: signalsToken,
});

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

auth = WorkOS.client.user_management.authenticate_with_password(
  client_id: "client_123456789",
  email: "marcelina@example.com",
  password: "i8uv6g34kd490s",
  ip_address: "210.123.170.80",
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  signals_id: signals_token
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

auth = client.user_management.authenticate_with_password(
    email="marcelina@example.com",
    password="i8uv6g34kd490s",
    ip_address="210.123.170.80",
    user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    signals_id="signals_token_value",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	auth, err := client.UserManagement().AuthenticateWithPassword(context.Background(), &workos.UserManagementAuthenticateWithPasswordParams{
		ClientID:  "client_123456789",
		Email:     "marcelina@example.com",
		Password:  "i8uv6g34kd490s",
		IPAddress: "210.123.170.80",
		UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
		SignalsID: signalsToken,
	})
	if err != nil {
		panic(err)
	}

	_ = auth
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$auth = $workos
    ->userManagement()
    ->authenticateWithPassword(
        email: "marcelina@example.com",
        password: "i8uv6g34kd490s",
        ipAddress: "210.123.170.80",
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        signalsId: $signalsToken,
    );

 import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.AuthenticateWithPasswordOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

AuthenticateWithPasswordOptions options =
    AuthenticateWithPasswordOptions.builder()
        .email("marcelina@example.com")
        .password("i8uv6g34kd490s")
        .ipAddress("210.123.170.80")
        .userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36")
        .signalsId(signalsToken)
        .build();

workos.userManagement.authenticateWithPassword(options);

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

JavaScript

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "authorization_code",
    "code": "01E2RJ4C05B52KKZ8FSRDAP23J",
    "ip_address": "210.123.170.80",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "signals_id": "signals_token_value"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const auth = await workos.userManagement.authenticateWithCode({
  clientId: 'client_123456789',
  code: authorizationCode,
  ipAddress: '210.123.170.80',
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  signalsId: signalsToken,
});

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

auth = WorkOS.client.user_management.authenticate_with_code(
  client_id: "client_123456789",
  code: authorization_code,
  ip_address: "210.123.170.80",
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  signals_id: signals_token
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

auth = client.user_management.authenticate_with_code(
    code="01E2RJ4C05B52KKZ8FSRDAP23J",
    ip_address="210.123.170.80",
    user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    signals_id="signals_token_value",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	auth, err := client.UserManagement().AuthenticateWithCode(context.Background(), &workos.UserManagementAuthenticateWithCodeParams{
		ClientID:  "client_123456789",
		Code:      authorizationCode,
		IPAddress: "210.123.170.80",
		UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
		SignalsID: signalsToken,
	})
	if err != nil {
		panic(err)
	}

	_ = auth
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$auth = $workos
    ->userManagement()
    ->authenticateWithCode(
        code: $authorizationCode,
        ipAddress: "210.123.170.80",
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        signalsId: $signalsToken,
    );

 import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.AuthenticateWithCodeOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

AuthenticateWithCodeOptions options =
    AuthenticateWithCodeOptions.builder()
        .code(authorizationCode)
        .ipAddress("210.123.170.80")
        .userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36")
        .signalsId(signalsToken)
        .build();

workos.userManagement.authenticateWithCode(options);

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.

JavaScript

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "urn:workos:oauth:grant-type:radar-email-challenge:code",
    "code": "123456",
    "radar_challenge_id": "radar_challenge_01HXYZ123456789ABCDEFGHIJ",
    "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

// The error from a previous authenticate call includes:
// - pendingAuthenticationToken
// - radarChallengeId

// User enters the code from their email...

const auth =
  await workos.userManagement.authenticateWithRadarEmailChallenge({
    clientId: 'client_123456789',
    code: userEnteredCode,
    radarChallengeId: radarChallengeId,
    pendingAuthenticationToken: pendingAuthenticationToken,
  });

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

# The error from a previous authenticate call includes:
# - pending_authentication_token
# - radar_challenge_id

# User enters the code from their email...

auth = WorkOS.client.user_management.authenticate_with_radar_email_challenge(
  client_id: "client_123456789",
  code: user_entered_code,
  radar_challenge_id: radar_challenge_id,
  pending_authentication_token: pending_authentication_token
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

# The error from a previous authenticate call includes:
# - pending_authentication_token
# - radar_challenge_id

# User enters the code from their email...

auth = client.user_management.authenticate_with_radar_email_challenge(
    code="123456",
    radar_challenge_id="radar_challenge_01HXYZ123456789ABCDEFGHIJ",
    pending_authentication_token="cTDQJTTkTkkVYxbn...",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	// The error from a previous authenticate call includes:
	// - PendingAuthenticationToken
	// - RadarChallengeID

	// User enters the code from their email...

	auth, err := client.UserManagement().AuthenticateWithRadarEmailChallenge(context.Background(), &workos.UserManagementAuthenticateWithRadarEmailChallengeParams{
		ClientID:                   "client_123456789",
		Code:                       userEnteredCode,
		RadarChallengeID:           radarChallengeID,
		PendingAuthenticationToken: pendingAuthenticationToken,
	})
	if err != nil {
		panic(err)
	}

	_ = auth
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

// The error from a previous authenticate call includes:
// - pendingAuthenticationToken
// - radarChallengeId

// User enters the code from their email...

$auth = $workos
    ->userManagement()
    ->authenticateWithRadarEmailChallenge(
        code: $userEnteredCode,
        radarChallengeId: $radarChallengeId,
        pendingAuthenticationToken: $pendingAuthenticationToken,
    );

 import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.AuthenticateWithRadarEmailChallengeOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

// The error from a previous authenticate call includes:
// - pendingAuthenticationToken
// - radarChallengeId

// User enters the code from their email...

AuthenticateWithRadarEmailChallengeOptions options =
    AuthenticateWithRadarEmailChallengeOptions.builder()
        .code(userEnteredCode)
        .radarChallengeId(radarChallengeId)
        .pendingAuthenticationToken(pendingAuthenticationToken)
        .build();

workos.userManagement.authenticateWithRadarEmailChallenge(options);

See the Radar email challenge error and authenticate with 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 in the WorkOS dashboard.

JavaScript

 # 1. Send the SMS challenge
curl --request POST \
  --url https://api.workos.com/user_management/radar_challenges \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn",
    "phone_number": "+15555550123"
  }
BODY
# Response includes verification_id

# User enters the code from their SMS...

# 2. Authenticate with the SMS code
curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "urn:workos:oauth:grant-type:radar-sms-challenge:code",
    "code": "123456",
    "verification_id": "verification_id_from_step_1",
    "phone_number": "+15555550123",
    "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

// The error from a previous authenticate call includes:
// - pendingAuthenticationToken

// 1. Send the SMS challenge
const { verificationId } =
  await workos.userManagement.sendRadarSmsChallenge({
    userId: 'user_01E4ZCR3C56J083X43JQXF3JK5',
    pendingAuthenticationToken: pendingAuthenticationToken,
    phoneNumber: '+15555550123',
  });

// User enters the code from their SMS...

// 2. Authenticate with the SMS code
const auth =
  await workos.userManagement.authenticateWithRadarSmsChallenge({
    clientId: 'client_123456789',
    code: userEnteredCode,
    verificationId: verificationId,
    phoneNumber: '+15555550123',
    pendingAuthenticationToken: pendingAuthenticationToken,
  });

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

# The error from a previous authenticate call includes:
# - pending_authentication_token

# 1. Send the SMS challenge
challenge = WorkOS.client.user_management.create_radar_challenge(
  user_id: "user_01E4ZCR3C56J083X43JQXF3JK5",
  pending_authentication_token: pending_authentication_token,
  phone_number: "+15555550123"
)

# User enters the code from their SMS...

# 2. Authenticate with the SMS code
auth = WorkOS.client.user_management.authenticate_with_radar_sms_challenge(
  client_id: "client_123456789",
  code: user_entered_code,
  verification_id: challenge.verification_id,
  phone_number: "+15555550123",
  pending_authentication_token: pending_authentication_token
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

# The error from a previous authenticate call includes:
# - pending_authentication_token

# 1. Send the SMS challenge
challenge = client.user_management.create_radar_challenge(
    user_id="user_01E4ZCR3C56J083X43JQXF3JK5",
    pending_authentication_token="cTDQJTTkTkkVYxbn...",
    phone_number="+15555550123",
)

# User enters the code from their SMS...

# 2. Authenticate with the SMS code
auth = client.user_management.authenticate_with_radar_sms_challenge(
    code="123456",
    verification_id=challenge.verification_id,
    phone_number="+15555550123",
    pending_authentication_token="cTDQJTTkTkkVYxbn...",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	// The error from a previous authenticate call includes:
	// - PendingAuthenticationToken

	// 1. Send the SMS challenge
	challenge, err := client.UserManagement().CreateRadarChallenge(context.Background(), &workos.UserManagementCreateRadarChallengeParams{
		UserID:                     "user_01E4ZCR3C56J083X43JQXF3JK5",
		PendingAuthenticationToken: pendingAuthenticationToken,
		PhoneNumber:                "+15555550123",
	})
	if err != nil {
		panic(err)
	}

	// User enters the code from their SMS...

	// 2. Authenticate with the SMS code
	auth, err := client.UserManagement().AuthenticateWithRadarSmsChallenge(context.Background(), &workos.UserManagementAuthenticateWithRadarSmsChallengeParams{
		ClientID:                   "client_123456789",
		Code:                       userEnteredCode,
		VerificationID:             challenge.VerificationID,
		PhoneNumber:                "+15555550123",
		PendingAuthenticationToken: pendingAuthenticationToken,
	})
	if err != nil {
		panic(err)
	}

	_ = auth
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

// The error from a previous authenticate call includes:
// - pendingAuthenticationToken

// 1. Send the SMS challenge
$challenge = $workos
    ->userManagement()
    ->createRadarChallenge(
        userId: "user_01E4ZCR3C56J083X43JQXF3JK5",
        pendingAuthenticationToken: $pendingAuthenticationToken,
        phoneNumber: "+15555550123",
    );

// User enters the code from their SMS...

// 2. Authenticate with the SMS code
$auth = $workos
    ->userManagement()
    ->authenticateWithRadarSmsChallenge(
        code: $userEnteredCode,
        verificationId: $challenge->verificationId,
        phoneNumber: "+15555550123",
        pendingAuthenticationToken: $pendingAuthenticationToken,
    );

 import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.AuthenticateWithRadarSmsChallengeOptions;
import com.workos.usermanagement.UserManagementApi.CreateRadarChallengeOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

// The error from a previous authenticate call includes:
// - pendingAuthenticationToken

// 1. Send the SMS challenge
CreateRadarChallengeOptions challengeOptions =
    CreateRadarChallengeOptions.builder()
        .userId("user_01E4ZCR3C56J083X43JQXF3JK5")
        .pendingAuthenticationToken(pendingAuthenticationToken)
        .phoneNumber("+15555550123")
        .build();

var challenge = workos.userManagement.createRadarChallenge(challengeOptions);

// User enters the code from their SMS...

// 2. Authenticate with the SMS code
AuthenticateWithRadarSmsChallengeOptions authOptions =
    AuthenticateWithRadarSmsChallengeOptions.builder()
        .code(userEnteredCode)
        .verificationId(challenge.getVerificationId())
        .phoneNumber("+15555550123")
        .pendingAuthenticationToken(pendingAuthenticationToken)
        .build();

workos.userManagement.authenticateWithRadarSmsChallenge(authOptions);

See the Radar SMS challenge error, send a Radar SMS challenge, and authenticate with 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 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.

JavaScript

 curl --request POST \
  --url "https://api.workos.com/radar/attempts" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "ip_address": "210.123.170.80",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "email": "marcelina@example.com",
    "auth_method": "Password",
    "action": "sign-in",
    "signals_id": "signals_token_value"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const attempt = await workos.radar.createAttempt({
  ipAddress: '210.123.170.80',
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  email: 'marcelina@example.com',
  authMethod: 'Password',
  action: 'sign-in',
  signalsId: signalsToken,
});

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

attempt = WorkOS.client.radar.create_attempt(
  ip_address: "210.123.170.80",
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  email: "marcelina@example.com",
  auth_method: "Password",
  action: "sign-in",
  signals_id: signals_token
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

attempt = client.radar.create_attempt(
    ip_address="210.123.170.80",
    user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    email="marcelina@example.com",
    auth_method="Password",
    action="sign-in",
    signals_id="signals_token_value",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	attempt, err := client.Radar().CreateAttempt(context.Background(), &workos.RadarCreateAttemptParams{
		IPAddress:  "210.123.170.80",
		UserAgent:  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
		Email:      "marcelina@example.com",
		AuthMethod: "Password",
		Action:     "sign-in",
		SignalsID:  signalsToken,
	})
	if err != nil {
		panic(err)
	}

	_ = attempt
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$attempt = $workos
    ->radar()
    ->createAttempt(
        ipAddress: "210.123.170.80",
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        email: "marcelina@example.com",
        authMethod: "Password",
        action: "sign-in",
        signalsId: $signalsToken,
    );

 import com.workos.WorkOS;
import com.workos.radar.RadarApi.CreateAttemptOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateAttemptOptions options =
    CreateAttemptOptions.builder()
        .ipAddress("210.123.170.80")
        .userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36")
        .email("marcelina@example.com")
        .authMethod("Password")
        .action("sign-in")
        .signalsId(signalsToken)
        .build();

workos.radar.createAttempt(options);

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.

JavaScript

 curl --request PUT \
  --url "https://api.workos.com/radar/attempts/radar_att_01HZBC6N1EB1ZY7KG32X" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "challenge_status": "success",
    "attempt_status": "success"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.radar.updateAttempt('radar_att_01HZBC6N1EB1ZY7KG32X', {
  attemptStatus: 'success',
  challengeStatus: 'success',
});

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.radar.update_attempt(
  id: "radar_att_01HZBC6N1EB1ZY7KG32X",
  attempt_status: "success",
  challenge_status: "success"
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.radar.update_attempt(
    id_="radar_att_01HZBC6N1EB1ZY7KG32X",
    attempt_status="success",
    challenge_status="success",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Radar().UpdateAttempt(context.Background(), &workos.RadarUpdateAttemptParams{
		ID:              "radar_att_01HZBC6N1EB1ZY7KG32X",
		AttemptStatus:   "success",
		ChallengeStatus: "success",
	})
	if err != nil {
		panic(err)
	}
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->radar()
    ->updateAttempt(
        id: "radar_att_01HZBC6N1EB1ZY7KG32X",
        attemptStatus: "success",
        challengeStatus: "success",
    );

 import com.workos.WorkOS;
import com.workos.radar.RadarApi.UpdateAttemptOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateAttemptOptions options = UpdateAttemptOptions.builder()
                                   .id("radar_att_01HZBC6N1EB1ZY7KG32X")
                                   .attemptStatus("success")
                                   .challengeStatus("success")
                                   .build();

workos.radar.updateAttempt(options);

See the Radar attempts API reference 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, enable enforcement from the Radar configuration page. At that point, Radar will begin returning challenges and blocks to your application.

Recommended steps:

Contact support or reach out in your shared Slack channel to enable Radar in the User Management APIs or the Standalone Radar API for your environment.
Complete your client-side and server-side integration using this guide.
Deploy your changes and verify that Radar decisions appear in the dashboard.
Review Radar’s logged decisions to make sure they match your expectations.
Enable enforcement when you’re confident in the integration.

Radar overview – dashboard, detections, configuration, managed lists, and custom restrictions
Authentication API reference – password, Magic Auth, OAuth/SSO authenticate endpoints
Radar email challenge – complete an email challenge
Radar SMS challenge – complete an SMS challenge
Send a Radar SMS challenge – send an SMS verification code
Radar attempts API – Standalone Radar risk assessment
@workos/radar-signals on npm – client signals library

Roles and Permissions Manage and assign roles and permissions to users

Up next

Radar Integration Guide

Introduction

When to use each mode

Client signals library

React

Vanilla JavaScript

Script tag

Radar in the User Management APIs

Key parameters

Sign up with password

Magic Auth

Sign in with password

Sign in with OAuth or SSO

Handling Radar challenges

Email challenges

SMS challenges

Block errors

Standalone Radar

Creating an attempt

Updating an attempt

Going live

Related resources