/
Contact usSee pricingStart building
    Introduction
    Device Fingerprinting
      Fingerprint Lookup
      Fingerprint Lookup (Deprecated)
      Set Rule
      Get Rules
      Set Verdict Reason Override
      Get Verdict Reasons
    Errors
      Overview
      Error object
      400
      401
      403
      404
      408
      499
      500
      503
Get support on SlackVisit our developer forum

Contact us

Fraud and Risk Prevention

/

API reference

/

Device Fingerprinting

/

Set Rule

Set Rule

POST
https://telemetry.stytch.com/v1/rules/set

Set a rule for a particular visitor_id, browser_id, visitor_fingerprint, browser_fingerprint, hardware_fingerprint, network_fingerprint, cidr_block, asn, or country_code. This is helpful in cases where you want to allow or block a specific user or fingerprint. You should be careful when setting rules for browser_fingerprint, hardware_fingerprint, or network_fingerprint as they can be shared across multiple users, and you could affect more users than intended.

You may not set an ALLOW rule for a country_code.

Rules are applied in the order specified above. For example, if an end user has an ALLOW rule set for their visitor_id but a BLOCK rule set for their hardware_fingerprint, they will receive an ALLOW verdict because the visitor_id rule takes precedence.

If there are conflicts between multiple cidr_block rules (for example, if the ip_address of the end user overlaps with multiple CIDR blocks that have rules set), the conflicts are resolved as follows:

  • The smallest block size takes precedence. For example, if an ip_address overlaps with a cidr_block rule of ALLOW for a block with a prefix of /32 and a cidr_block rule of BLOCK with a prefix of /24, the rule match verdict will be ALLOW.
  • Among equivalent size blocks, BLOCK takes precedence over CHALLENGE, which takes precedence over ALLOW. For example, if an ip_address overlaps with two cidr_block rules with blocks of the same size that return CHALLENGE and ALLOW, the rule match verdict will be CHALLENGE.

Body parameters

action* string

The action that should be returned by a fingerprint lookup for that identifier with a RULE_MATCH reason. The following values are valid: ALLOW, BLOCK, CHALLENGE, or NONE. For country codes, ALLOW actions are not allowed. If a NONE action is specified, it will clear the stored rule.

visitor_id string

The visitor ID we want to set a rule for. Only one identifier can be specified in the request.

browser_id string

The browser ID we want to set a rule for. Only one identifier can be specified in the request.

visitor_fingerprint string

The visitor fingerprint we want to set a rule for. Only one identifier can be specified in the request.

browser_fingerprint string

The browser fingerprint we want to set a rule for. Only one identifier can be specified in the request.

hardware_fingerprint string

The hardware fingerprint we want to set a rule for. Only one identifier can be specified in the request.

network_fingerprint string

The network fingerprint we want to set a rule for. Only one identifier can be specified in the request.

cidr_block string

The CIDR block we want to set a rule for. You may pass either an IP address or a CIDR block. The CIDR block prefix must be between 16 and 32, inclusive. If an end user's IP address is within this CIDR block, this rule will be applied. Only one identifier can be specified in the request.

asn string

The ASN we want to set a rule for. The ASN must be the string representation of an integer between 0 and 4294967295, inclusive. Only one identifier can be specified in the request.

country_code string

The country code we want to set a rule for. The country code must be a valid ISO 3166-1 alpha-2 code. You may not set ALLOW rules for country codes. Only one identifier can be specified in the request.

expires_in_minutes int

The number of minutes until this rule expires. If no expires_in_minutes is specified, then the rule is kept permanently.

description string

An optional description for the rule.

Response fields

request_id string

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

status_code int

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.

action string

The action that will be returned for the specified identifier.

browser_id string

The browser ID that a rule was set for.

visitor_id string

The visitor ID that a rule was set for.

visitor_fingerprint string

The visitor fingerprint that a rule was set for.

browser_fingerprint string

The browser fingerprint that a rule was set for.

hardware_fingerprint string

The hardware fingerprint that a rule was set for.

network_fingerprint string

The network fingerprint that a rule was set for.

cidr_block string

The CIDR block that a rule was set for. If an end user's IP address is within this CIDR block, this rule will be applied.

asn string

The ASN that a rule was set for.

country_code string

The country code that a rule was set for.

expires_at string

The timestamp when the rule expires. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.

const stytch = require('stytch');

const client = new stytch.Client({
  project_id: 'PROJECT_ID',
  secret: 'SECRET',
});

const params = {
  action: "CHALLENGE",
  visitor_id: "visitor-6139cbcc-4dda-4b1f-b1c0-13c08ec64d72",
  expires_in_minutes: 120,
};

client.fraud.rules.set(params)
  .then(resp => { console.log(resp) })
  .catch(err => { console.log(err) });
RESPONSE 200
200
​
{
  "action": "CHALLENGE",
  "browser_id": "",
  "visitor_id": "visitor-6139cbcc-4dda-4b1f-b1c0-13c08ec64d72",
  "visitor_fingerprint": "",
  "browser_fingerprint": "",
  "hardware_fingerprint": "",
  "network_fingerprint": "",
  "asn": "",
  "cidr_block":,
  "country_code": "",
  "expires_at": "2033-01-01T00:00:00Z",
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "status_code": 200
}
RESPONSE 401
200
​
{
  "status_code": 401,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "unauthorized_credentials",
  "error_message": "Unauthorized credentials.",
  "error_url": "https://stytch.com/docs/api/errors/401"
}
RESPONSE 429
200
​
{
  "status_code": 429,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "too_many_requests",
  "error_message": "Too many requests have been made.",
  "error_url": "https://stytch.com/docs/api/errors/429"
}
RESPONSE 500
200
​
{
  "status_code": 500,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "internal_server_error",
  "error_message": "Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.",
  "error_url": "https://stytch.com/docs/api/errors/500"
}