Mitigation API

The Mitigation API provides real-time bot decisions that enables customers to block, allow or otherwise deceive bots to protect their 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",
    "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",
    "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": false,
  "action": "allow",
  "threat_category": null,
  "threat_profile": "VAL",
  "policy_name": "MyPolicy"
}

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": ""
    }
  }
}

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: An 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
    • 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 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) IPv4 or IPv6 of the sender of request to the API server that calls the Mitigation API.
    • 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 request to the API server that calls the Mitigation API.
    • ui: (optional, string) User ID - provide 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 is fails business logic validation, usually associated with 400-level HTTP status codes
  • datatoken: Field provided from the tag via OZ_DT field
  • payload: Field provided from the tag via OZ_SG field
  • session: Field provided from the tag via 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:

Environment Value to Pass
Apple iOS 324715238
Android com.example.Example

client_error

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

ck

Cookie ID - provide cookie id (or session ID) as defined by 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 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 then the url (see below) in the case of SPAs (single page apps), where the user is on one page, however the request hits an enpoint with a different path. For native in-app mobile, there won't be a url (unless its 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, 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:

Description Value
Undefined† 0
Account Login 1
Account Creation 2
Password Reset 3
Password Update 4
Profile Update 5
Reputation Click 6
Spin (song play) 7
Payment / Transaction 8
Generic Form Fill 9
Generic Button Click 10
Sensitive Data Scraping 11
Scraping Protection 12

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

Example Event Result event_success value
Login attempt Successful login true
Login attempt Wrong password login false
Registration attempt Username taken false
Registration attempt Successful registration / signup true

ip

Provide full IPv4 or IPv6 address.

Examples:

Traffic Type Value to Pass
IPv4 173.239.79.196
IPv6 (format) fe80::f03a:3aff:fed6:7a2f

pw_match

Boolean, true is 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 - provide user id as defined by 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.