Skip to main content
All CollectionsLead / Form Protection
Server-side verification
Server-side verification

Ensure your form submission are verified against additional abuse

E
Written by Eurico Doirado
Updated over 4 months ago

Server-side token verification

Even if you implement client-side (JavaScript) blocking, we recommend adding a server-side check to further prevent abuse.

To verify the token validity on the server side, follow the steps below:

  1. Retrieve the token from the submitted form validation result. In the JavaScript example, it is the saf_token (result.t) parameter sent through the form.

  2. Submit the token to the API for verification (see below).

  3. Block, or log separately, submissions that fail to pass the token verification check.

Submit the token to the verification API

Include the following parameters in body of the request:

Parameters

Description

api_key

The API key generated for the tracker

token

The token retrieved from the submitted form's parameters (e.g. saf_token)

type
​

Use the same type / action name as the one used in the JavaScript configuration

ip

The IP (v4 or v6) address used in the form submission (optional)

ua

The user agent used in the HTTP headers of the form submission (optional)

Below is an example of a cURL request to the API (replace the <api_key>, <token> and <tracker> parameters):

curl -X POST -d 'api_key=<api_key>' -d 'token=<token>' -d 'type=<type>' -d 'ip=<ip>' -d 'ua=<user_agent>' https://sp-trk.com/api/verify/<tracker>

The 'ip' parameter is optional. If you use it, the expected format is in its text representation:

  • IPv4 example: 1.1.1.1

  • IPv6 example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334

Similarly, the 'user_agent' parameter is also optional. If you use it, pass the value exactly as it was received in the HTTP headers. An example of a user agent is:

Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.4 Mobile/15E148 Safari/604.1

API response

If a call is successful, the API returns an http status 200 OK.

Additionally, the body of the response content will contain a JSON object as follows:

  • score (float): a score of 0.0 indicates that no problem was found. The token is valid and the form submission should be accepted. On the other hand a score of 1.0 indicates an issue has been detected. In this case the reason is described in the reason field.

  • request_id (string): the request id is a unique ID associated with the verification request. It is encoded as a string for compatibility reasons but can safely be cast into an int64.

  • timestamp (optional, string): the datetime (in the iso8601 format) at which the token was generated. If the token is invalid and couldn't be read, this may be omitted.

  • reason (optional, string): when a verification fails, we include the reason. It can be one the following:

    • "ivt": the submission triggered one or more invalid traffic classifications (see below). An example would be a bot submitting the form.

    • "expired": the token was generated too long ago. See below for token usage and lifetime restrictions.

    • "duplicate": this token has already been verified. A token can only be verified once. See below for token usage and lifetime restrictions.

    • "invalid_signature": the token has either been tampered.

    • "no_token": the token is empty.

  • ivt_subcategories (optional, array of strings): when a verification fails because an invalid access was detected, this field will contain the reason(s). It can one or many of the following:

    • "bot": traces of automation were detected for this user.

    • "spoofed_device": the User-Agent does not match the OS/Browser/Device used by the user. An example would be a User-Agent declaring to be an iPhone running on the latest iOS while in reality it is running on a Linux virtual machine environment.

    • "geo_masking": a vpn, proxy or TOR exit nodes used to hide the original IP and potential spoof the location of the user.

    • "suspicious_ip": the IP of the user has been recently used in other cybercrimes, often indicating a device that has been infected with malware

    • "datacenter": the IP of the user belongs to a datacenter.

    • "invalid_ua": submission from a User-Agent that is clearly not representing a browser. This could be for example a web request sent from a program like Python or Java.

    • "repeat": when a browser exceeds the user-configured maximum number of submissions per window of time (e.g. more than 5 submission in the last 6 hours).

Below is an example of successful validation:

{
  "request_id": "123",
  "score": 0.0,
  "timestamp": "2022-01-01T00:00:00Z"
}

And an example of a token that failed the validation because a bot was detected:

{
  "request_id": "456",
  "score": 1.0,
  "timestamp": "2022-01-01T00:00:00Z",
  "ivt_subcategories": ["bot", "datacenter"],
  "reason": "ivt"
}

Token usage restriction and maximum lifetime

Tokens generated by Spider AF are single use only. This is meant to prevent certain attacks. Submitted the same token a second time will return the status code duplicated.

Additionally, these tokens are valid for a maximum of two minutes after they are generated. Afterwards, the token will be considered invalid and the status code expired will be returned.

Did this answer your question?