Pular para o conteúdo principal

Uso da API GKTinc (Integração sem SDK)

Objetivo​

Este documento descreve o uso direto da API GKTinc para integrar a partir de qualquer linguagem (C, Java, Python, etc.) sem usar o SDK oficial.

A API fornece dois endpoints principais:

  • get_challenge_level: obtém o nível de desafio para o IP atual.
  • validate_challenge: valida a solução enviada pelo front-end.

Observação: os endpoints abaixo seguem o mesmo formato usado pelo SDK atual.

URL Base​

https://api.guardiankey.io/

Autenticação​

Todas as chamadas exigem o cabeçalho:

X-API-Key: <your_api_key>

1) Obter Nível de Desafio​

Endpoint​

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

Headers​

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

Exemplo (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

Resposta (exemplo)​

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

2) Validar Desafio​

Endpoint​

POST /v3/tinc/{protectiongroup_hashid}/validate_challenge

Headers​

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

Payload (JSON)​

Campos obrigatórios/relevantes:

  • agent_id: identificador do agente/sistema (string)
  • gktinc_solution: string base64 gerada pelo JS
  • salt: sha1(api_key + protectiongroup_hashid)
  • client_ip: IP do cliente
  • url: host + caminho (sem o protocolo)
  • once: identificador de sessão (ex.: session id)
  • form_payload_size: tamanho do payload do formulário (int)
  • form_input_element_value: valor do campo monitorado (ex.: nome de usuário)
  • time: timestamp (epoch)
  • challenge_level: nível de desafio (int) (opcional, recomendado)

Exemplo (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
    }' \
    https://api.guardiankey.io/v3/tinc/YOUR_HASHID/validate_challenge

Resposta (exemplo)​

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

Como gerar campos críticos​

salt​

salt = sha1(api_key + protectiongroup_hashid)

url​

No SDK, o valor é "host + path" (sem o protocolo). Exemplo:

example.com/wp-login.php

once​

Pode ser um identificador de sessão. No WordPress, use session_id().

form_payload_size​

Tamanho do payload POST/GET menos o campo gktinc_solution. No SDK:

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

Fluxo completo (sem SDK)​

  1. No back end, obtenha client_ip e chame get_challenge_level (opcional).
  2. No front end, carregue gktinc-setup-latest.js e inicialize com uma configuração equivalente a gktinc_config.
  3. Ao submeter, o JS gera gktinc_solution e o adiciona ao POST.
  4. No back end, chame validate_challenge com o payload completo.
  5. Se action == BLOCK, negue o acesso; caso contrário, aceite.

Observações importantes​

  • Sem o JS da GKTinc não há gktinc_solution e a validação irá falhar.
  • Se sua integração for fail-open, pule a validação quando gktinc_solution não estiver presente.
  • O endpoint base é HTTPS; evite desabilitar SSL em produção.