Policies
A flexible rules engine with triggers and actions
Overview
While the three Castle risk scores provide a good starting point for weeding out fraudulent behavior, Policies is the foundation that lets you write business domain specific rules to make sure you're catching fraud specific to your platform.
With policies, it is easy to set up rules for e.g.
- Denying transactions over $500, happening from non-US countries and from new accounts
- Challenging logins with too many prior failed attempts from the same IP
- Preventing signups from devices with multiple prior accounts connected to it
Policies are applied when Castle's /risk
or /filter
API endpoints are called, and each API response will contain a policy
object with the matching policies, as well as a policy.action
field set to allow
, challenge
, or deny
.
How policies work
Triggers and Actions
The basics of a policy consists of configuring two types of settings:
The Trigger, which is the condition that will activate the Policy, such as matching
- A specific Event type,
- A Segment
- The contents of one or many Lists
- Risk score and signal settings
Once the triggering conditions are defined, you'll configure what will happen whenever they are met, i.e. the Action
- Returned API action,
allow
,challenge
ordeny
- Whether an item should be added to one or many lists
Segments
Policies apply to Segments, which are sets of filters that allow you to select things like device traits, user traits, or event properties to group events. The default Segment is "All Events". By separating Segments from Policies, Castle allows you to define re-usable behaviors like "Transactions over $500".
To configure a target Segment, go to the Policy Segments page in the Dashboard.
Event evaluation
When a Policy returns a verdict (such as action: challenge
in the Castle /risk
response), these things have occurred in order:
- Event (i.e.
$login
) sent to Castle/risk
endpoint - Event has a Policy configured (i.e. "Deny" for
$login
) - Event context matches the Segment filters specified in the Policy
- Event evaluated for risk scores and risk signals defined by Policy
- Event Risk Score/Signals meet the Policy definition (i.e. risk 90+), so
deny
is returned
Versioning
Castle comes pre-configured with several Policies. You’re allowed to modify these default Policies. If you wish to restore previous states of Policies, there is a Changelog from which you can select the version you wish to restore.

A Policy Changelog Allows Reversion to Prior Versions
Organization
Policies are grouped by event to give you a better understanding of the actions taken throughout the different points in your application. These events include registrations, logins, profile updates, transactions, and password resets.
Policies are evaluated in order, from top to bottom, for each event grouping. You can easily re-order them as you see fit. The most narrow-scope and restrictive policies (i.e. deny
) should usually be at the top of the list because they should be evaluated for matches first.
Creating a policy
Step 1. Create a new policy
To complete this step:
- Click "Create a New Policy"
- Enter a Policy Name
- Select a Triggering Event (i.e. $login, $registration, etc.)

Create a New Policy
Step 2. Configure the policy
This step has multiple parts, which are all part of the "Configure a Policy" widget. Each part is covered below
Step 2a. (optional) Choose the triggering segment
To complete this step, select the Triggering Segment that will trigger evaluation for matches to this policy.
Configuring a Segment is an advanced use-case that becomes easier after you have started sending traffic that matches your Policy. A Segment is a set of event-property-based filters. Segments are matched prior to Policy evaluation.
You can view and filter the last 100 events sent to Castle's /risk
endpoint via the Castle Dashboard Segments Tool. This is the easiest way to verify filter performance when creating Segments.
The default segment for a policy is "All Events".
If you are configuring your new policy prior to defining the target segment, no worries! You can click the "Create New" button next to the Segment selector, and the configurator will allow you to define a new segment. Return to the "Policies" page when you are finished to continue where you left off.
Step 2b. Choose the verdict
The verdict is the inline action that Castle's API response returns to your application: allow
, challenge
, or deny
.
To complete this step:
- Select the action that you want delivered when this policy evaluates to true
- (Optional) Make this a Log Only policy for evaluation purposes
Choose whether you want the Castle API response to include action: deny
or action: challenge
when this policy evaluates to true. Also select whether the device that receives this verdict should receive the verdict every time this policy triggers, or only if the device is unapproved.
Step 2c. Adjust risk score
You can modify the risk score range for which the policy evaluates true. Castle recommends these default settings:
- 60-100:
challenge
- 90-100:
deny
The reason there is overlap in the scores is that deny
policies should be ordered above challenge
policies, so they will always be evaluated first. That way, if you have a need to disable a deny
policy, the events that used to receive deny
verdicts will receive challenge
verdicts.
Step 2d. Risk signals
Castle calculates many risk signals based on event properties, and we expose a handful of often-requested signals here for you to use in order to force specific verdicts when you see these signals. The configuration UI contains informative explanations for the signals, so please refer to your Dashboard Policy Configuration page for details.
Step 2e. Device risk memory
Castle can "remember" the risk of a device. This becomes useful when, for example, a device triggers a challenge
verdict because it matches one custom Policy, but the next time that device is used it does not match the same custom policy. You can choose whether Castle should "remember" the device risk in order to deliver a challenge
or deny
verdict in the future, when the future contextual risk would otherwise have Castle return an allow
verdict.
Step 2f. Summary
Click the "Summary" button to read a summary of your policy. This summary should make sense based on the settings you configured. It might be good to have a team member double-check the policy summary.
Step 3. Enable and reorder
To complete this step:
- (Optional) Reorder the policy to an appropriate position
- Enable the policy
When you have multiple Policies for the same event, there is no harm in having policies overlap in their triggers or definitions, but Policy ordering becomes very important. You will notice that Castle's default policies enable deny
verdicts for risk score ranges 90-100, and challenge
verdicts for risk score ranges 60-100. This is fine, as long as the deny
policy is evaluated before the challenge
policy. Otherwise, if the deny
policy were below the challenge
policy, the deny
policy would never have a chance to evaluate to true because the challenge
policy would always be the first-matched policy for that event.
The most important thing to consider here is that policies are evaluated in top-down order. For most cases, this means that deny
policies should be ordered above challenge
policies. If you are unsure about the effects of reordering your policies, you can create Log Only policies to evaluate these effects before modifying the "real" enabled policies.
Updated 3 months ago