Validation

Validate a request

This endpoint allows you to check if a user request should be allowed or blocked.

Headers

• content-type (string): Should be set to application/json.
• x-api-key (string): Your API key.

Body

• url (string): The URL the user requested.
• method (string): The request method i.e. GET, POST etc.
• ip (string): The IP address of the user.
• referrer (string): The referer header on the request.
• headers (object): The headers on the request.
• cookie (string): The value of the _centinel cookie attached to the request. This cookie is used for session tracking across both interstitial and continuous protection modes.

Request

curl -X POST 'https://validator.centinelanalytica.com/validate' \
  -H 'content-type: application/json' \
  -H 'x-api-key: API_KEY' \
  -d '{"url": "https://example.com", "method": "GET", "ip": "127.0.0.1", "cookie": "1234567890", "referrer": "https://example.com", "headers": { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" }}'

Successful Response

{
  "success": true,
  "decision": "allow" | "block" | "redirect" | "not_matched",
  "response_html": "string",
  "cookies": [{ "name": "string", "value": "string", "path": "string", "domain": "string" }]
}

The response_html and cookies properties are only present in the case of a redirect response. The response_html contains base64 encoded HTML of the interstitial page.

Error Response

{
  "success": false,
  "status": number,
  "message": string,
}

You will only receive an error response if the validation request was invalid. Check the errors property for more information.

Responses

Allow

The request has been passed validation and should be allowed access to the site as normal.

Not Matched

The request URL did not match any protected endpoint and should be allowed access to the site as normal.

Block

The request has failed validation and should be blocked.

Redirect

Show the interstitial challenge verification page. This only occurs when the validation system determines that additional verification is required.

When you receive a REDIRECT decision, your backend should decode the base64 encoded HTML from the response_html field (base64 decode then UTF-8 decode) and return it to the user's browser.