Skip to main content

​
Overview

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

​
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.
See Reference guides for a full list of all verdict reasons or use the Get Verdict Reasons endpoint.

​
Prerequisites

  • An existing Stytch project in the Dashboard.
  • The project_id and secret for your project’s Test environment. These can be found under your project’s Project ID & API keys section in the Dashboard.
  • Device Fingerprinting enabled for your project.

​
Steps

1

Select which verdict reason to override

You will need the verdict reason and action to associate with it.For the chosen verdict reason, you can decide the new action: ALLOW, BLOCK, or CHALLENGE.
2

Call Set Verdict Reason Override

Call the Set Verdict Reason Override endpoint:
curl --request POST \
  --url https://telemetry.stytch.com/v1/verdict_reasons/override \
  -u '${projectId}:${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"
  }'
This example sets VIRTUAL_MACHINE to ALLOW instead of the default reason.
3

Review the new override

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 '${projectId}:${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 response also includes verdict.verdict_reason_overrides that contains information about overrides applied to a specific lookup.
4

Delete the override

To delete the override, call the Set Verdict Reason Override endpoint with an action of NONE:
curl --request POST \
  --url https://telemetry.stytch.com/v1/verdict_reasons/override \
  -u '${projectId}:${secret}' \
  -H 'Content-Type: application/json' \
  --data '{
      "verdict_reason": "VIRTUAL_MACHINE",
      "override_action": "NONE"
  }'