Skip to content
Browse API reference

Risk

Used to request a risk evaluation from Castle's API. The most obvious use of this is for login requests, where the API can indicate malicious and questionable circumstances. Read more in the Prevent Account Takeovers section. See the List of Recognized Events for supported events.

Request

POST https://api.castle.io/v1/risk

Request body

context
required
object

The context object contains information about the originating request, including IP address and HTTP headers.

Note: This field can be skipped by setting skip_context_validation to true.

properties
object

User defined properties associated with this device

product
object
session
object

Additional session information from your system

created_at
string (date-time)

The default value is the time of which the event was received by Castle. If you’re passing events in a delayed fashion, such as via an event queue, you should make sure to set this field to the time of which the event was tracked and put into the queue.

request_token
required
string

Token generated from a client. Check out our quick start guide to generate a request_token.

Note: This field can be skipped by setting skip_request_token_validation to true.

user
required
object
skip_request_token_validation
booleanDefault: false

Skip request_token validation. Enable when it's impossible to obtain Castle request_token (e.g., third-party API calls). When enabled, Castle risk scores are not calculated.

Set to true to make the request_token field optional.

skip_context_validation
booleanDefault: false

Skip context validation. Enable when HTTP request context is not providing useful insight (e.g., third-party API calls from Data Center IP).

Set to true to make the context field optional.

expand
string[]

Include additional properties into API response. This option is currently in beta and available only to select customers.

type
required
stringDefault: $challenge

Castle supported events available for this endpoint

status
required
string
$requested$succeeded$failed
authentication_method
object
challenge
object

Challenge object containing information about the event that triggered this challenge

Response

201
object

Castle Event Context

401
No body

You are missing the Authorization header, or the API secret is missing or incorrect.

403
No body

The request is rejected because the service is not enabled for this account.

422
object

The request body is unprocessable by the API. Make sure it conforms to the specified format for the endpoint.

429
No body

You performed too many requests. You should back off and retry using the exponential backoff algorithm.

500
No body

There’s an issue on our end.