STstytch
Fraud

Set

Changed on

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.
post/v1/rules/set

Request

  • Base URL
    https://telemetry.stytch.com
  • Auth
    HTTP basic

Request body

action'ALLOW' | 'CHALLENGE' | 'BLOCK' | 'NONE' required
visitor_idstring

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

browser_idstring

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

visitor_fingerprintstring

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

browser_fingerprintstring

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

hardware_fingerprintstring

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

network_fingerprintstring

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

expires_in_minutesinteger

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

descriptionstring

An optional description for the rule.

cidr_blockstring

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.

country_codestring

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.

asnstring

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.

Response

Successful response

request_idstring required

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.

action'ALLOW' | 'CHALLENGE' | 'BLOCK' | 'NONE' required
status_codeinteger required

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.

visitor_idstring

The visitor ID that a rule was set for.

browser_idstring

The browser ID that a rule was set for.

visitor_fingerprintstring

The visitor fingerprint that a rule was set for.

browser_fingerprintstring

The browser fingerprint that a rule was set for.

hardware_fingerprintstring

The hardware fingerprint that a rule was set for.

network_fingerprintstring

The network fingerprint that a rule was set for.

expires_atstring

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.

cidr_blockstring

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.

country_codestring

The country code that a rule was set for.

asnstring

The ASN that a rule was set for.

Changes