A complete integration

All the steps necessary to complete a successful integration with Castle

Introduction

Castle lets you visualize your customers' journeys down to the level of individual button clicks, so you can identify the most sophisticated types of fraud that otherwise go unnoticed.

Using the Castle API, you can send user activity (which we call events) from both your frontend and backend, and it will assess the risk associated with each action.

The following guide explains all the events supported by Castle, with recommendations on which ones to integrate. At a high level, the steps to a successful integration are:

  1. Add the client-side integration to collect device and behavioral data, as well as monitor user actions such as page views, form submissions, and any other business-specific user activity. Both browser and mobile clients are supported. Many times, this first part of the integration will give you a good picture of how much fraud and abuse you have on your platform before you proceed to the next step.
  2. Send server-side key activities such as registration, login, profile updates, and transactions, as well as any business-critical custom events. In contrast to client-side events, server-side events can also be used for real-time blocking of activity, and they will return a set of data such as risk score, risk signals and policy settings.
  3. Configure alerting via webhooks or Slack to get notified whenever Castle and use the results to your fraud operations.
  4. Configure inline blocking to make use of the inline risk assessment capabilities of the Risk and Filter APIs and take action against suspicious users in real-time.

Phase 1. Monitoring client-side activity

Castle's client-side SDKs plays a central role in a Castle integration by providing device fingerprinting, user interaction monitoring as well as in-browser event tracking.

All the client-side SDKs, web and mobile, have two main purposes:

  • Tracking client-side events. Track important in-app events directly from the client. This is where we recommend you get started.
  • Creating request tokens. A unique token which should be passed to the server whenever Castle's backend APIs are called. This won't be needed until you start sending data to the server-side APIs.

See the guides on how to integrate Castle in browser and mobile clients to kick of the integration.

👍

The quickest integration path

Most developers will start by adding the Browser SDK to their web application as this integration resembles other lightweight analytics platforms and will rely on frontend code to send data to Castle. You can always check out the quickstart to get a better grasp of how the client-side integration works.

Phase 2. Protecting server-side actions

By now, you're probably already integrated the client-side SDKs and monitoring user activity, so it's time to utilize its second use-case -- generating request tokens.

Generating request tokens through the client-side SDKs is required in order for Castle to profile the user and the devices when calling the Risk and Filter APIs. There is also the Log API outlined below, which doesn't require a request token, but as a result it won't calculate risk scores, signals, nor device fingerprints.

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 integrating Castle in the browser and into mobile apps.

The Risk, Filter, and Log APIs

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

  • Risk API — track user activity and receive a real-time risk assessment for authenticated users. This is the API you'll be using the most.
  • Filter API — a variant of 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.

There's also the Log API, that you'll be less likely to use during the initial integration:

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

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.

APIEventStatus
Risk$registration$succeeded👉 Recommended
Filter$registration$failedOptional

👍

Complete the guide for sending registration activity

Login

Use $login events to track user logins and stop account takeover attempts from humans and 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. Additionally, there's a $logout event that can be useful in both account takeover and abuse scenarios.

APIEventStatus
Risk$login$succeeded👉 Recommended
Filter$login$failed👉 Recommended
Risk$logout$succeededOptional

👍

Complete the guide for sending 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.

APIEventStatus
Risk$profile_update$attempted👉 Recommended
Risk$profile_update$succeededOptional
Risk$profile_update$failedOptional

👍

Complete the guide for sending profile update activity

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.

APIEventStatus
Risk$transaction$attempted👉 Recommended
Risk$transaction$succeededOptional
Risk$transaction$failedOptional

👍

Complete the guide for sending 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.

APIEventStatus
Risk$challenge$requestedOptional
Risk$challenge$succeededOptional
Risk$challenge$failedOptional

👍

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

Password reset flow

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.

Once the user received the instructions on how to reset the password, typically an email or text message with a reset link, you'll send the $profile_reset event to the Risk API to mark the completion of the reset flow. Note this event is named profile, not password, since it allows you to also track accounts that other properties such as their phone number or authentication method reset.

APIEventStatus
Filter$password_reset_request$attemptedOptional
Filter$password_reset_request$succeededOptional
Filter$password_reset_request$failedOptional
Risk$profile_reset$attemptedOptional
Risk$profile_reset$succeededOptional
Risk$profile_reset$failedOptional

👍

Complete the guide for sending password reset activity

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 any of the scores are above 0.9. See the guides for each Activity for specific recommendations on how to implement this.

Example response from Risk and Filter APIs

Note that the risk field has been replaced by the scores.account_abuse field. These two values will always be identical, and it's recommended that you leverage the latter.

{
  "risk": 0.67,
  "scores": {
    "account_abuse": {
        "score": 0.67
    },
    "account_takeover": {
        "score": 0.77
    },
    "bot": {
        "score": 0.34
    }
  },
  "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: Verify that the client-side SDKs for web and native mobile apps are forwarding the request_token on 100% of the request to your backend.
:white-check-mark: Verify that you're forwarding the end-user's IP in production and not the private, internal IP from your firewall or CDN.
: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

Proof-Of-Concept (POC) guide

A POC is a more hands-on version of the self-service trial where our customer success team gets involved to help you coordinate the integration and ensure that your success criteria are met at the end of the evaluatoin.

A typical POC will be 30 days long, starting at the point of when full POC implementation is deployed into your production environment. The self-serve trial, on the other hands, starts the clock at the time of signup.

To speed up coordination during the POC, we will invite your team to a shared Slack channel and and also invite technical resources on our end.

Minimal POC integration

We normally recommend doing the POC on in your web environment since then we won't need to go through mobile app store approvals simply to test things out. However, if you're a mobile-only business, we will do the Mobile SDK(s) instead of the Browser SDK.

  1. Integrate the Browser SDK
  2. Send page views from the Browser SDK
  3. Integrate the Server SDK
  4. Pass the request_token from the Browser SDK to the Server SDK
  5. Send successful registrations from the Server SDK. Make sure the user object is as complete as possible. You'll be re-using it for all the server calls.
  6. Send successful logins from the Server SDK
  7. Send failed logins from the Server SDK
  8. Send profile updates from the Server SDK. The changeset details object can be added after the POC.
  9. Send transactions from the Server SDK. The transaction details object can be added after the POC.

What’s Next