Referência de Backend e API

📚 Referência de Backend e API

Referência da chamada de backend do XE, do gkas_config que você envia à página e da função de init do coletor.

🔒 O gkas_solution é um token opaco. Seu conteúdo e formato são intencionalmente não documentados. O seu backend o repassa inalterado ao checkaccessxe; você nunca lê, monta ou interpreta esse token.

---

Frontend: gkas_init(...)

Fornecido pelo script hospedado do GuardianKey (gkas-setup-latest.js). Liga‑se ao formulário de login e monta o gkas_solution no submit.

gkas_init(gkas_config, formElement, nomeDoCampoUsuario, debug = false)

Parâmetro	Tipo	Descrição
gkas_config	object	O { url, salt, once, time } que o seu backend gerou para este carregamento.
formElement	HTMLFormElement	O formulário de login a ser ligado.
nomeDoCampoUsuario	string	Nome do input de usuário — vinculado à tentativa.
debug	boolean	Opcional. Mostra um painel de diagnóstico. Padrão false.

No submit, o coletor injeta um campo oculto gkas_solution no formulário, de modo que o POST que o seu backend recebe já o inclui automaticamente.

---

gkas_config (página → coletor)

Montado por carregamento pelo seu backend e embutido na página. Os mesmos campos que o backend depois passa ao checkaccessxe.

Campo	Tipo	Descrição
url	string	Origem + caminho da página/endpoint. Parte do challenge vinculado.
salt	string	Um salt por implantação.
once	string	Nonce de uso único — gere por carregamento, guarde na sessão, valide no POST.
time	string	Timestamp Unix (como string) da geração.

{
  "url":  "https://app.exemplo.com/login.php",
  "salt": "demo_salt",
  "once": "9f1c…",
  "time": "1754428303"
}

---

Backend: checkaccessxe(...)

Da guardiankey.class.php de referência. Envia o evento de backend e o gkas_solution do frontend ao GuardianKey, retornando uma decisão em JSON.

function checkaccessxe(
    $username,
    $useremail = "",
    $url, $salt, $once, $time,
    $gk_solution,        // o gkas_solution opaco do POST, inalterado
    $attempt = "0"       // "0" = senha correta, "1" = falhou
)

Parâmetro	Descrição
$username	O identificador do usuário, do formulário de login.
$useremail	Email opcional; "" se não usado.
$url, $salt, $once, $time	Os mesmos valores do gkas_config desta tentativa.
$gk_solution	O gkas_solution recebido no POST — repasse inalterado.
$attempt	"0" se a senha estava correta, "1" caso contrário.

Internamente ele faz POST para …/v3/gkas/{authgroupid}/checkaccessxe com o header X-Api-Key, empacotando um backend_data (evento) e um frontend_data ( gkas_solution, url, salt, once, time ). Nenhuma mudança na classe de referência é necessária — ela repassa o token como está.

GKconfig (credenciais)

Construa o cliente com as suas credenciais GuardianKey. Elas ficam apenas no backend — nunca na página.

$GKconfig = [
    'agentid'     => 'sdk',
    'key'         => 'BASE64_KEY',
    'iv'          => 'BASE64_IV',
    'service'     => 'SeuNomeDeServico',
    'orgid'       => 'YOUR_ORG_ID',
    'authgroupid' => 'YOUR_AUTHGROUP_ID',
    'api_key'     => '',                  // derivado abaixo
    'reverse'     => 'True',
];
// api_key = sha256(key + iv)
$GKconfig['api_key'] = hash('sha256', $GKconfig['key'] . $GKconfig['iv']);

---

Resposta

checkaccessxe retorna uma string JSON com o mesmo modelo do Auth Security clássico. O campo decisivo é response:

{
  "response": "ACCEPT",
  "risk": 5.047,
  "risk_context": 5.0,
  "risk_intel": 0.05,
  "country": "Brazil",
  "client_os": "Linux",
  "client_ua": "Chrome",
  "eventId": "3e1c389c1ae49efc…",
  "message": "Origin not found in the threat DB."
}

response	Ação
ACCEPT	Permitir o acesso.
NOTIFY	Permitir, opcionalmente com verificação extra / notificação ao usuário.
BLOCK	Negar o acesso, mesmo que a senha esteja correta.

⚠️ Sempre valide o response antes de conceder acesso. No BLOCK, retorne uma mensagem genérica ("usuário ou senha inválidos") para evitar vazamento de informação.

---

Veja também

• Integração web — ligação ponta a ponta página + backend.
• Integração do Auth Security — o fluxo clássico checkaccess.
• SDK Mobile — o mesmo fluxo XE para apps nativos.