A complete integration

All the steps necessary to complete a successful integration with Castle

:bulb: Tip: By reading the quickstart guide first, you'll have a better understanding of the concepts mentioned in this guide, and how Castle works in general.

Introduction

In order to mitigate fraud and suspicious behavior with Castle, you need to integrate the server-side SDKs into your backend. These SDKs give you an easy way to communicate with the Castle HTTP API endpoints and are used to send user activities (which are sent to Castle as events) and to assess the risk of these activities. We'll outline all the activity events that Castle supports, as well as recommend the ones that put you in the best position for detecting, investigating and preventing fraud.

At a high level, the most important steps to a successful Castle integration are:

  1. Add the client-side integration to collect device and user behavioral data. Castle supports both web and mobile clients.
  2. Send key activities to Castle to create an audit trail for each user. We recommend starting with "$login" and "$registration", but the more activities you send, the easier it becomes to identify fraudulent users. See all the supported activities below.
  3. Make use of the inline risk assessment capabilities of the Risk APIs to detect and take action against suspicious users, or use the Filter API to block software bots.
  4. Set up Webhooks or Slack notifications to get notified whenever Castle detects suspicious behavior and use them to automate parts of your fraud operations.

Client-side integration

Client-side SDKs are required in order for Castle to track user activity and fingerprint each device through the Risk and Filter APIs. Only in rare circumstances would you omit this integration step and instead resort to using the Log API outlined below.

Device and user behavioral data is tokenized and automatically passed to your backend services as a request token. The Castle back-end SDKs in turn pass this data to the Castle service.

See the guides for the supported clients.

Server-side integration – The Risk, Filter, and Log APIs

Back-end SDKs used to track user activity and take action against suspicious users. There are three primary back-end APIs that you can use.

  • Risk API — track user activity and receive a real-time risk assessment for authenticated users
  • Filter API — similar to the Risk API but designed to do an early assessment of anonymous visitors before they register or log in to your service. You can also call this API from the edge to block bot and spam requests before they reach your back-end app.
  • Log API — primarily used for when you want to send out of band activity into Castle in order to complete the user journey. Examples of activity can be logs from your authentication provider or chargeback events from your payment processor. This API is more lax on which fields are sent and doesn't require IP and request header data, but it will parse it whenever they're provided, however, it will not calculate a risk score or generate any behavioral signals.

Understanding Activities, Event and Status

An activity is anything a user can do in your app, and in the context of Castle and fraud detection, it's something that you want to track and assess the risk of. Activities are sent to Castle as events and the outcome is sent as a status. For example, a user login would be sent as a $login event and depending on whether the user entered the correct credentials or not, the status would either be $succeeded or $failed.

Each status will have a distinct meaning for each activity, but below is the general difference between the different statuses. The most important to understand are $succeeded and $failed:

  • $succeeded - The activity was completed with a successful outcome. E.g. in the case of registration, a user was successfully created, and for logins, the entered credentials matched the ones one file.
  • $failed - The activity was completed, but resulted in a failed outcome. E.g. in the case of registration, the user already existed, and for logins, the entered credentials didn't match the ones one file.
  • (optional) $attempted - Immediately when the user tries to perform an action, such as login or registration. Typically, right after a form post, but before any backend logic is invoked. This makes the $attempted status suitable for blocking malicious requests early, to reduce server load in case of attacks, such as in an edge environment

Testing server-side calls without request tokens

A request_token parameter is required to be sent with every request to the Filter and Risk API endpoints, but sometimes that part of the integration hasn't been implemented yet, or you need an easier way to test different scenarios with your server-side code. Test Tokens makes testing your server-side integration of Castle a breeze.

Supported activities

Below is a list of supported activities and which API to use them with. In general, we recommend tracking as many activities as possible. Doing so will improve Castle's risk models and provide a better audit trail when you are investigating fraudulent activity.

📘

How much to integrate?

A minimal integration typically involves sending $registration and $login events, but in order to maximize the accuracy of Castle's risk models, you should send all the recommended activities, as well as any $custom events that are important to your business. Risk scores for $profile_update and $transaction activities have higher accuracy when preceded by a $registration or $login activity.

Registration

Use $registration events to track new account creation and stop fake and synthetic identities from registering new accounts. If a user follows all the proper steps to create an account, use the Risk API with a status of $succeeded. The Risk API will then return a Castle risk assessment for the user, which you can use to allow the account to be created, or block it if Castle detects a suspicious user. If a user fails to follow the proper steps to create an account, use the Log API and a status of $failed.

API

Event

Status

Risk

$registration

$succeeded

👉 Required

Filter

$registration

$failed

Optional

👍

Complete the guide for adding the registration activity

Login

Use $login events to track user logins and stop account takeover attempts from humans and software bots. In addition to assessing successful logins, failed login tracking is an important aspect of detecting credential stuffing or brute force attacks.

If a user successfully logs in (i.e. provides correct credentials), use the Risk API with a status of $succeeded. The Risk API will return a Castle risk assessment for the user, which you can use to allow, challenge or deny the login. If you put users through a challenge workflow, the guide Automating Account Recovery for information on the Castle APIs to use to notify Castle about the outcome of the challenge.

If a user does not successfully log in, use the Filter API with a status of $failed.

API

Event

Status

Risk

$login

$succeeded

👉 Required

Filter

$login

$failed

Highly recommended in order to detect automated login attacks

👍

Complete the guide for adding the login activity

Profile update

Send $profile_update events to track when users update their email, phone, password, address, or payment information. Profile updates are only supported for authenticated users. As with $login events, the Risk API will return a Castle risk assessment. This assessment can be used to allow, challenge or deny the profile update.

API

Event

Status

Risk

$profile_update

$attempted

Optional

Risk

$profile_update

$succeeded

👉 Recommended

Risk

$profile_update

$failed

Optional

Transaction

Send $transaction events to track bank or credit card transactions. Both successful and failed transactions are important data points in detecting fraud. As with $login events, the Risk API will return a Castle risk assessment. This assessment can be used to allow, challenge or deny a transaction.

API

Event

Status

Risk

$transaction

$succeeded

👉 Recommended

Risk

$transaction

$failed

👉 Recommended

👍

Complete the guide for adding the transaction activity

Challenge

Send $challenge events to track step-up challenge flows such as MFA or KYC. These events are helpful to see in a user activity timeline, and they also help train Castle's risk models.

API

Event

Status

Risk

$challenge

$requested

Optional

Risk

$challenge

$succeeded

👉 Recommended

Risk

$challenge

$failed

Optional

👍

See the guide for account takeover workflows for more details on how to send challenge activity

Password reset request

Send $password_reset_request events to track attempts to reset a user password, which can be an early signal of an account takeover. With an incorrectly implemented password reset flow, the attacker can run a user enumeration attack, which can be used to increase the success rate of an account takeover attack. By sending the below events to Castle, you can catch and mitigate fraud at an early stage. The Filter API returns a Castle risk assessment, which can be used to allow or deny the password reset request.

:bulb: Note that the Risk API isn't available for this event type, since a user isn't authenticated at the time of the password reset request.

API

Event

Status

Filter

$password_reset_request

$attempted

Optional

Filter

$password_reset_request

$succeeded

Optional

Filter

$password_reset_request

$failed

Optional

Using the inline API response

The API response from both the Risk and Filter APIs can be used to write granular risk logic. Read the complete list of signals and the guide on Policies for more information.

📘

As a starting point, we recommend blocking any attempts where the risk score is above 0.9. See the guides for each Activity for specific recommendations on how to implement this.

Example response from Risk and Filter APIs

{
  "risk": 0.67,
  "signals": {
    "new_device": {},
    "new_country": {},
    "proxy_ip": {},
    "impossible_travel": {},
    "multiple_accounts_per_device": {},
  },
  "policy": {
    "action": "challenge",
    "name": "Trigger MFA on suspicious logins",
    "id": "e14c5a8d-c682-4a22-bbca-04fa6b98ad0c",
    "revision_id": "b5cf794e-88c0-426e-8276-037ba1e7ceca"
  },
  // The response from the Risk API includes an additional device object,
  // which is a reference to the user's current device, and which can be
  // used in the Castle feedback APIs. This object is not included in the 
  // response from the Filter API
  "device": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IlQyQ"
  }
}

Checklist for going live

Once you have added all the recommended activities above, make sure to verify the following before going live in production:

:white-check-mark: Ensure that the client-side SDKs are properly installed and used both for web and native mobile apps, and that the request_token is forwarded correctly.
:white-check-mark: Check the debugger for any warnings or errors. See the Quickstart section for guidance
:white-check-mark: Forward all the HTTP headers from the original client request in the context.headers field. Use the helper methods in the Castle SDKs
:white-check-mark: Switch to a Production API Key


Did this page help you?