Overriding verdict reasons
For every fingerprint lookup, Device Fingerprinting recommends a specific verdict action. You can override the default action to customize the recommendations based on your application and traffic.
For example, the VIRTUAL_MACHINE warning flag results in a CHALLENGE by default, but you might expect many legitimate users to be using an enterprise browser (that runs in a virtual machine). You can override verdict reasons so that VIRTUAL_MACHINE maps to an ALLOW verdict instead.
This is most useful for customizing Protected Auth decisioning. If you are directly integrating with the Device Fingerprinting API, you can also use verdict reason overrides to change decisioning logic without needing to write and deploy new backend code.
For a list of all verdict reasons and default actions, see the documentation for Warning Flags (Verdict Reason Overrides) or use the Get Verdict Reasons API endpoint.
Tutorial
Before you start
In order to complete this guide, you'll need the following:
- A Stytch project. If you don't have one already, sign up for a Stytch Workspace.
- The project_id and secret for the Test environment you would like to use. These values can be accessed from the API keys section of the Stytch dashboard. You'll need to pass these values into the Authorization request header for most Stytch API calls.
- Device Fingerprinting enabled. If you don't have the product enabled, reach out to Stytch here.
1Decide what verdict reason to override
You will need the verdict reason and action to associate with it. See the documentation for Warning Flags (Verdict Reasons) or use the Get Verdict Reasons API endpoint.
For the chosen verdict reason, you can decide the new action: ALLOW, BLOCK, or CHALLENGE.
2Call the Set Verdict Reason Override endpoint
To set the override, call the Set Verdict Reason Override endpoint. The following example code sets VIRTUAL_MACHINE to ALLOW instead of the default reason.
curl --request POST \
--url https://telemetry.stytch.com/v1/verdict_reasons/override \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
--data '{
"verdict_reason": "VIRTUAL_MACHINE",
"override_action": "ALLOW",
"description": "Allow instead of challenge VMs because we expect lots of legitimate VM users"
}'3Review the new override
Next, you can use the Get Verdict Reasons endpoint to confirm your change:
curl --request POST \
--url https://telemetry.stytch.com/v1/verdict_reasons/list \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{}'The resulting list will contain an entry showing the override for VIRTUAL_MACHINE:
{
"verdict_reason_overrides": [
# ...
{
"verdict_reason": "VIRTUAL_MACHINE",
"default_action": "CHALLENGE",
"override_action": "ALLOW",
"override_created_at": "2025-01-02T03:04:05Z",
"description": "Allow instead of challenge VMs because we expect lots of legitimate VM users"
}
]
}The Fingerprint Lookup API response also contains a field, verdict.verdict_reason_overrides, that contains information about overrides applied to a specific lookup.
4Delete the new override
To delete the override, call the Set Verdict Reason Override endpoint with an action of NONE. To unset the override you created above:
curl --request POST \
--url https://telemetry.stytch.com/v1/verdict_reasons/override \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
--data '{
"verdict_reason": "VIRTUAL_MACHINE",
"override_action": "NONE"
}'What's next
To learn more about other decisioning options, see Decisioning with Device Fingerprinting.