Skip to content
Browse API reference

Filter

Used to block bots and bad traffic early in the request chain, typically at registration. Read more in the Protecting the Login section. See the List of Recognized Events for supported events.

At minimum the User-Agent key is required in the headers object.

Request

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

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 (request_token)

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
object
params
object
matching_user_id
string

User id related connected with the request

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: $registration

Castle supported events available for this endpoint

status
stringDefault: $attempted
$attempted$failed
authentication_method
object

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.

500
No body

There’s an issue on our end.