Skip to main content

GKTinc API Usage (Integration without SDK)

Purpose​

This document describes direct use of the GKTinc API to integrate from any language (C, Java, Python, etc.) without using the official SDK.

The API provides two main endpoints:

  • get_challenge_level: obtains the challenge level for the current IP.
  • validate_challenge: validates the solution sent by the front end.

Note: the endpoints below follow the same format used by the current SDK.

Base URL​

https://api.guardiankey.io/

Authentication​

All calls require the header:

X-API-Key: <your_api_key>

1) Get Challenge Level​

Endpoint​

GET /v3/tinc/{protectiongroup_hashid}/get_challenge_level/{client_ip}

Headers​

X-API-Key: <your_api_key>
Content-Type: application/json

Example (cURL)​

curl -X GET \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    https://api.guardiankey.io/v3/tinc/YOUR_HASHID/get_challenge_level/203.0.113.10

Response (example)​

{
    "action": "ACCEPT",
    "challenge_level": 3,
    "sign": "...",
    "client_ip": "203.0.113.10",
    "country": "BR",
    "city": "Sao Paulo"
}

2) Validate Challenge​

Endpoint​

POST /v3/tinc/{protectiongroup_hashid}/validate_challenge

Headers​

X-API-Key: <your_api_key>
Content-Type: application/json

Payload (JSON)​

Required/relevant fields:

  • agent_id: identifier of the agent/system (string)
  • gktinc_solution: base64 string generated by the JS
  • salt: sha1(api_key + protectiongroup_hashid)
  • client_ip: client IP
  • url: host + path (without protocol)
  • once: session identifier (e.g., session id)
  • form_payload_size: size of the form payload (int)
  • form_input_element_value: value of the monitored input (e.g., username)
  • time: timestamp (epoch)
  • challenge_level: challenge level (int) (optional, recommended)
  • user_agent: user agent string from the client (string).
  • sec_ch_ua: Sec-CH-UA client hint header (string).
  • sec_ch_ua_mobile: Sec-CH-UA-Mobile client hint (string).
  • sec_ch_ua_platform: Sec-CH-UA-Platform client hint (string).

Example (cURL)​

curl -X POST \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "agent_id": "gktinc-php-sdk-WordPress",
        "gktinc_solution": "BASE64...",
        "salt": "sha1(api_key+hashid)",
        "client_ip": "203.0.113.10",
        "url": "example.com/wp-login.php",
        "once": "SESSION_ID",
        "form_payload_size": 123,
        "form_input_element_value": "username",
        "time": 1710000000,
        "challenge_level": 3,
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36",
        "sec_ch_ua": "\"Chromium\";v=\"112\", \"Google Chrome\";v=\"112\", \"Not:A-Brand\";v=\"99\"",
        "sec_ch_ua_mobile": "?0",
        "sec_ch_ua_platform": "\"Windows\""
    }' \
    https://api.guardiankey.io/v3/tinc/YOUR_HASHID/validate_challenge

Response (example)​

{
    "action": "ACCEPT",
    "score": 0,
    "ip_policy": "not_listed",
    "country": "BR",
    "city": "Sao Paulo"
}

How to generate critical fields​

salt​

salt = sha1(api_key + protectiongroup_hashid)

url​

In the SDK, the value is "host + path" (without the protocol). Example:

example.com/wp-login.php

once​

Can be a session identifier. In WordPress, use session_id().

form_payload_size​

Size of the POST/GET payload minus the gktinc_solution field. In the SDK:

form_payload_size = strlen(serialize(POST)) - strlen(gktinc_solution)

Full flow (without SDK)​

  1. On the back end, obtain client_ip and call get_challenge_level (optional).
  2. On the front end, load gktinc-setup-latest.js and initialize with a config equivalent to gktinc_config.
  3. On submit, the JS generates gktinc_solution and appends it to the POST.
  4. On the back end, call validate_challenge with the full payload.
  5. If action == BLOCK, deny access; otherwise, accept.

Important notes​

  • Without the GKTinc JS there is no gktinc_solution and validation will fail.
  • If your integration is fail-open, skip validation when gktinc_solution is not present.
  • The base endpoint is HTTPS; avoid disabling SSL in production.