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

# Attempts

A Radar attempt represents a sign-in or signup attempt and includes context such as IP address and user agent. The Radar engine assesses attempts for risk and returns a decision that you can use to drive behavior in your application.

## Create an attempt

Assess a request for risk using the Radar engine and receive a verdict.

:::code-group

```bash language="curl" title="Request" tab="1"
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": "49.78.240.97",
        "user_agent": "Mozilla/5.0",
        "email": "user@example.com",
        "auth_method": "Password",
        "action": "sign-in"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

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

WorkOS.client.radar.create_attempt(
  ip_address: "49.78.240.97",
  user_agent: "Mozilla/5.0",
  email: "user@example.com",
  auth_method: "Password",
  action: "sign-in"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

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

client.radar.create_attempt(
    ip_address="49.78.240.97",
    user_agent="Mozilla/5.0",
    email="user@example.com",
    auth_method="Password",
    action="sign-in",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

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

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

	_, err := client.Radar().CreateAttempt(context.Background(), &workos.RadarCreateAttemptParams{
		IPAddress:  "49.78.240.97",
		UserAgent:  "Mozilla/5.0",
		Email:      "user@example.com",
		AuthMethod: "Password",
		Action:     "sign-in",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

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

$workos
    ->radar()
    ->createAttempt(
        ipAddress: "49.78.240.97",
        userAgent: "Mozilla/5.0",
        email: "user@example.com",
        authMethod: "Password",
        action: "sign-in",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.radar.RadarApi.CreateAttemptOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateAttemptOptions options = CreateAttemptOptions.builder()
                                   .ipAddress("49.78.240.97")
                                   .userAgent("Mozilla/5.0")
                                   .email("user@example.com")
                                   .authMethod("Password")
                                   .action("sign-in")
                                   .build();

workos.radar.createAttempt(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Radar.CreateAttemptAsync(new RadarCreateAttemptOptions {
    IpAddress = "49.78.240.97",
    UserAgent = "Mozilla/5.0",
    Email = "user@example.com",
    AuthMethod = "Password",
    Action = "sign-in",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::radar::CreateAttemptParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .radar()
        .create_attempt(
            CreateAttemptParams {
                ip_address: "49.78.240.97".into(),
                user_agent: "Mozilla/5.0".into(),
                email: "user@example.com".into(),
                auth_method: "Password".into(),
                action: "sign-in".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "verdict": "block",
  "reason": "Detected enabled Radar control",
  "attempt_id": "radar_att_01HZBC6N1EB1ZY7KG32X",
  "control": "bot_detection",
  "blocklist_type": "ip_address"
}
```

:::

## Update a Radar attempt

You may optionally inform Radar that an authentication attempt or challenge was successful using this endpoint. Some Radar controls depend on tracking recent successful attempts, such as impossible travel.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```rb language="ruby" title="Request" tab="1"
require "workos"

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

WorkOS.client.radar.update_attempt(id: "radar_att_01HZBC6N1EB1ZY7KG32X")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

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

client.radar.update_attempt(id_="radar_att_01HZBC6N1EB1ZY7KG32X")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

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

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

	_, err := client.Radar().UpdateAttempt(context.Background(), "radar_att_01HZBC6N1EB1ZY7KG32X")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

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

$workos->radar()->updateAttempt(id: "radar_att_01HZBC6N1EB1ZY7KG32X");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.radar.updateAttempt("radar_att_01HZBC6N1EB1ZY7KG32X");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Radar.UpdateAttemptAsync("radar_att_01HZBC6N1EB1ZY7KG32X");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .radar()
        .update_attempt("radar_att_01HZBC6N1EB1ZY7KG32X")
        .await?;

    Ok(())
}
```

:::

### POST /radar/attempts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ip_address` | string | Yes | The IP address of the client |
| `user_agent` | string | Yes | The user agent of the client |
| `email` | string | Yes | The email address of the user making the attempt |
| `auth_method` | "Password" \| "Passkey" \| "Authenticator" \| ... | Yes | The authentication method used for the attempt Possible values: `Password` `Passkey` `Authenticator` `SMS_OTP` `Email_OTP` `Social` `SSO` `Other` |
| `action` | "sign-up" \| "sign-in" | Yes | The action of the attempt. `sign-up` or `sign-in` |
| `signals_id` | string | No | An optional Radar signals ID for the request. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `verdict` | "allow" \| "block" \| "challenge" | The verdict of the risk assessment. |
| `reason` | string | A human-readable reason for the verdict. |
| `attempt_id` | string | Unique identifier of the authentication attempt. |
| `control` | "bot_detection" \| "brute_force_attack" \| "impossible_travel" \| ... | The Radar control that triggered the verdict. Only present if the verdict is `block` or `challenge`. |
| `blocklist_type` | "ip_address" \| "domain" \| "email" \| ... | The type of blocklist entry that triggered the verdict. Only present if the control is `restriction`. |

### PUT /radar/attempts/{id}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `challenge_status` | "success" | No | The status of the challenge |
| `attempt_status` | "success" | No | The status agent of the attempt |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The ID of the Radar attempt |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |