Mitigation API

The Mitigation API provides real-time bot decisions that let you block, allow or otherwise deceive bots to protect your internet properties from bot fraud.

Decision Endpoint

URL: https://vesper.p.botx.us/decision

Method: POST

Headers

• Authorization: Bearer {TOKEN}
• Content-Type: application/json

Request Payload

{
  "client_ds": {
    "ap": "com.Example.example",
    "app_version": "1.0.3",
    "client_error": false,
    "ck": "ddeedb6f4adf80dd2d8b0eb81c69da13",
    "custom": {
      "example": "example"
    },
    "dv": "c3f927f4-3ef9-4b53-8887-d794c4daea82",
    "endpoint": "https://example.com/api/v1/login",
    "et": "1",
    "event_success": false,
    "ip": "127.0.0.1, 70.41.3.18, 150.172.238.178",
    "pw_match": false,
    "ref": "https://example.com",
    "server_error": false,
    "si": "xyz1234",
    "ti": "4d2ab6f3189e72166c3e8ca424aa1528b",
    "timestamp": 631152000000,
    "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.87 Safari/537.36",
    "ui": "04a1ad8a40e296df0d385e46c3796cd3",
    "url": "https://example.com/login",
    "username": "4738c51401e7437245e9b80d73147ce35f862ea3",
    "user_exists": false,
    "validation_error": false
  },
  "datatoken": "",
  "payload": "",
  "session": "",
  "policy_name": "MyPolicy"
}

Response Payload

{
  "bot": true,
  "action": "allow",
  "threat_category": ["BOT-ENT_BVR"],
  "threat_profile": "BOT",

  "policy": {
    "policy_name": "MyPolicy",
    "rule_label": "IPAllowList",
    "policy_version": 104
  },

  "entity_fingerprint": {
    "safe": true,
    "class": "aggregator",
    "name": "Mint"
  }
}

Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "http://humansecurity.com/application_integrity/vesper/response/1.0/schema.json",
  "type": "object",
  "title": "Vesper response schema",
  "examples": [
    {
      "bot": false,
      "action": "allow",
      "threat_category": null,
      "threat_profile": "VAL"
    }
  ],
  "required": [
    "bot",
    "action",
    "threat_category",
    "threat_profile"
  ],
  "additionalProperties": false,
  "properties": {
    "bot": {
      "$id": "#/properties/bot",
      "type": "boolean",
      "title": "Bot decision",
      "description": ""
    },
    "action": {
      "$id": "#/properties/action",
      "type": "string",
      "title": "Action",
      "description": "Generally \"allow\" or \"block\" but may be overriden by the Policy Engine"
    },
    "threat_category": {
      "$id": "#/properties/threat_category",
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "^[A-Z]+-[A-Z_]+$": {"type": "boolean"}
          }
        },
        {
          "type": "null"
        }
      ],
      "title": "Threat Category",
      "description": "The collection of bot subcategories if a bot was detected",
      "examples": [
        null,
        {
          "BOT-BOT": true
        }
      ]
    },
    "threat_profile": {
      "$id": "#/properties/threat_profile",
      "type": "string",
      "enum": [
        "VAL",
        "NSD",
        "BOT"
      ],
      "title": "Threat Profile",
      "description": ""
    }
  }
}

Response fields

For every request you send to the Mitigation API, HUMAN will return a response with the following fields. These fields provide information about how an event was categorized and the recommended action for that event.

• action: A string that describes the recommended action for the event. For example, based on the policy that HUMAN applied to the event, we may return a block string and recommend that you block the user who drove that event. If you'd like to incorporate these recommendations into your bot mitigation workflow, you must configure your website or application to take action accordingly.
• bot: A Boolean value that, when true, indicates that HUMAN determined the event was driven by a bot.
• threat_profile: A string that describes whether HUMAN classified the event as a bot (BOT), nonstandard (NSD), or valid (VAL).
• threat_category: An array that contains the threat categories associated with the event. See Taxonomy for more details.
• policy: An object that contains the policy that HUMAN applied to the request.
  • policy_name: The name of the policy that HUMAN applied to the event.
  • rule_label: The label of the specific rule that was triggered when the policy was applied.
  • policy_version: The version number of the policy that HUMAN applied to the event. Versions can be helpful if you need to review events that were evaluated based on an older version of a custom policy.
• entity_fingerprint: If HUMAN determines that an event was driven by a bot, the Mitigation API will return the entity_ fingerprint object, which includes additional information about whether or not that bot was classified as “safe”. This object contains the following fields:
  • safe: A Boolean value that, when true, indicates that this event was driven by a non-malicious bot or automated script. These safe bots include bots listed on the IAB Spiders and Bots List and a variety of additional bots that HUMAN has classified as beneficial or otherwise harmless.
  • class: The type of identified bot or script. "Possible values are crawler, aggregator, and monitor. If the value of safe is false, this field will be omitted.
  • name: The name of the identified bot or script (e.g., ‘Google’, ‘Mint’). If the value of safe is false, this field will be omitted.

Request Fields

Note: For optional fields, omit the key-value pair if you are not providing the value. For the url field, it is possible that an attacker sends requests directly to your backend and omits this value, in which case you can pass along the empty value.

• client_ds: A key-value mapping of signals provided by the server making the request.
  • ap: (optional, string) (In-App Mobile only) Mobile App ID or Bundle ID.
  • app_version: (optional, string) The application version formatted as major.minor.fix.
  • client_error: (optional, boolean) Whether the request to the API server is malformed or invalid, usually associated with 400-level HTTP status codes.
  • ck: (optional, string) Cookie ID - provide cookie id (or session ID) as defined by the client system. This field may be hashed.
  • custom: (optional, object) Key-value pairs of arbitrary, additional signals sent for improved detection purposes. All keys and values must be of type string.
  • dv: (optional, string) (In-App Mobile only) Device ID: IDFA (iOS), or AAID (Android).
  • endpoint: (optional, string) The URL of the API endpoint hit by the submission of the protected event.
  • et: (required, string) Event Type - an ENUM value representing the type of interaction / transaction to be protected.
  • event_success: (optional, boolean) Whether the protected event was successful on the server side.
  • ip: (required, string) The IPv4 or IPv6 address of the client who made a request to the Mitigation API. If a request contains multiple IP addresses (which may occur if your servers are behind a load balancer or proxy), the X-Forwarded-For request header will combine these IP addresses and store them in a chain. HUMAN will always use the first IP address in a chain as the value of the ip parameter, so you must configure your load balancer to ensure that the first IP address in this chain matches the IP address of the client who initiated the request.
  • pw_match: (optional, boolean) (Login use-case only) Whether the password is correct.
  • ref: (optional, string) The full URL (protocol, domain, and path) of where the user came from before the target event. Exclude any GET (query parameters) and hash values. This URL should match the URL in the browser URL bar for the web page or view before the user navigated to the page or view where the protected interaction occurs. This value will likely need to be collected on the front-end and passed along to the backend.
  • server_error: (optional, boolean) Whether a server error occurred during the API response, usually associated with 500-level HTTP status codes.
  • si: (optional, string) Site ID - client-defined site identifier.
  • ti: (optional, string) Transaction ID - unique identifier for the event as defined by the client.
  • timestamp: (required, integer) Unix timestamp in milliseconds representing the time that the request is sent to the Mitigation API. Generate this timestamp as late as possible before sending the request to the Mitigation API.
  • ua: (required, string) User Agent of the sender of the request to the API server that calls the Mitigation API.
  • ui: (optional, string) User ID - User id as defined by client system.
  • url: (required, string) The full URL (protocol, domain, and path) of where the target event originated. Exclude any GET (query parameters) and hash values. This should match the URL in the browser URL bar when viewing the web page or view where the protected interaction occurs. This value is normally available in the HTTP Referer header in the request to your backend.
  • username: (optional, string) SHA1 hashed value of the username.
  • user_exists: (optional, boolean) (Login use-case only) Whether the applicable user exists.
  • validation_error: (optional, boolean) Whether the request to the API server fails business logic validation, usually associated with 400-level HTTP status codes.
• datatoken: Field provided from the tag via the OZ_DT field.
• payload: Field provided from the tag via the OZ_SG field.
• session: Field provided from the tag via the OZ_TC field.
• policy_name: (optional, string) Field provider by the customer that indicates the Policy Engine DSL script to invoke upon the decision.

Field Details

ap

App ID - for In-App Mobile, provide the App ID / Bundle ID, and maintain case (do not alter case by changing all to lowercase or all to uppercase).

Examples:

app_version

The application version formatted as major.minor.fix (i.e. semantic versioning). This field is critical if BotGuard is used to protect native mobile applications.

client_error

Boolean - true if the client request is malformed or invalid, else false.

ck

Cookie ID - provide cookie id (or session ID) as defined by the client system. This field may be hashed.

Example: CK_1007665, ddeedb6f4adf80dd2d8b0eb81c69da13

custom

Optionally provide custom key: value pairs associated with the event. The pairs must be a dictionary under the key "custom". Both key and value must be strings. These fields are client / business specific parameters and values, which aid in our detection efforts to identify bot or malicious activity.

Example Keys: album, coupon_code, categoryA, ontologyX, account_age, last_pw_reset

dv

Device ID - For mobile in-app traffic provide the Device ID - IDFA (iOS), or AAID (Android).

Example: c3f927f4-3ef9-4b53-8887-d794c4daea82, 00000000-0000-0000-0000-000000000000†

† - in cases where user has limited tracking or opted-out.

endpoint

The full URL (protocol, domain, and path) of the endpoint for the POST or GET event. Exclude any GET (query parameters) and hash values.

Example: https://abc.example.com/api/login

Note: This can be different than the url (see below) in the case of SPAs (single page apps), where the user is on one page, however the request hits an endpoint with a different path. For native in-app mobile, there won't be a url (unless it's a webview), but there will be an endpoint associated with the event (this field).

et

Event Type - an ENUM value representing the type of interaction / transaction to be protected. If the tag is not associated with an event to protect then exclude this field (i.e. mo=0).

Please ensure that Event Types 1 and 2 are only used for Account Login and Account Creation. This is critical for detection accuracy.

Populate with one of the following values:

† - if no specific event type applies - use default 0 or exclude.

Example: et=1, et=4

event_success

Boolean - true if attempted event succeeded, else false. If the event is not associated with a result, exclude this field.

ip

Provide full IPv4 or IPv6 address.

Examples:

pw_match

Boolean - true if the password matched the username for the given attempt.

ref

The full URL (protocol, domain, and path) of where the user came from before the target event.

Example: https://example.com/home

server_error

Boolean - true if infrastructure issues have been detected, else false.

si

Site ID - client-defined site identifier.

Example: xyz1234, 32928168991, registration

ti

Transaction ID - unique identifier for the event as defined by the client. Useful for joining datasets, e.g. Transaction Level Exports (TLX) and client logs. This is useful for identifying tag evasion.

Example: T_1005211 ,4d2ab6f3189e72166c3e8ca424aa1528

Note: If no unique ID exists in your system - generate a UUID using best practices. Besides passing this ID through the Tag, it will also need to be passed to the Mitigation API.

timestamp

The timestamp field should be a Unix timestamp in milliseconds representing the time that the request is sent to the Mitigation API. Generate this timestamp as late as possible before sending the request to the Mitigation API.

Example: 631152000000

ua

Provide the full User Agent string of where the event originated.

Example:\ Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.87 Safari/537.36

ui

User ID - user id as defined by the client system. Useful for joinability of records between our data and your internal client data. This field may be hashed.

Example: U_1001228, 04a1ad8a40e296df0d385e46c3796cd3

url

The full URL (protocol, domain, and path) of where the target event originated. Exclude any GET (query parameters) and hash values.

Example: https://abc.example.com/login

username

Provide a hashed (use sha1) value of the username. If not available this field is to be excluded or left blank.

Example algorithm: (u) -> sha1(u.username)

Example: bb9fcec60a45771c2cbb83ea2997a58ee821692d

Note: If the user doesn't exist you should still pass this value.

user_exists

Boolean - true if the user exists in client system, else false.

validation_error

Boolean - true if validation rules were applied but failed, else false.

Decision endpoint for Fastly integration

URL: https://vesper.p.botx.us/decision

Method: GET

Headers

• Authorization: Bearer {TOKEN}
• Content-Type: application/json

Payload headers

When making a request to the Mitigation API, you must include payload-related data with your request by adding specific headers. All requests must include the X-Decision-Client-Ds header as well as one of the following:

1. The X-Decision-Decision-Token header or
2. The combined oz_dt, oz_sg, and oz_tc headers.

These headers adhere to the following formats:

Since headers have a size limit, you may need to break down each header into several smaller sub-headers if you're sending a large amount of data. HUMAN will accommodate this overflow so long as your sub-headers follow a sequential naming syntax. For example, you can split the oz_dt header into four smaller headers named oz_dt0, oz_dt1, oz_dt2 and oz_dt3.

Response headers

The Mitigation API returns its responses in the headers of the response object. These response headers adhere to the following formats: