Sentinela
← Ir para Home Preços Teste seu domínio Observatório v0.56.4

Sentinela API Doc

Referência técnica da API do Sentinela — CAPTCHA avançado e inteligência de rede/e-mail da PANGEIA.

✓ Tudo nesta página está em produção — POST /v1/challenge/new, POST /v1/challenge/verify, POST /v1/check, POST /v1/feedback, GET /v1/attempts/<id>, POST /v1/lookup, GET /v1/network/lookup e POST /v1/email/lookup: Challenge Engine, Risk Engine (regras próprias, confidence/evidence, loop de feedback), canal de contestação, e Network/Email/Intermediary Intelligence (país, ASN, datacenter, cloud, CDN, Tor, WHOIS). Nenhum endpoint fictício, nenhuma spec preliminar — se está documentado aqui, dá pra chamar agora.

0)MVP disponível agora — proteger login/cadastro

Três chamadas, nessa ordem, protegem qualquer formulário de login ou cadastro contra bot de criação de conta e brute force de senha — inclusive credential stuffing com IP rotativo, porque o limite mais apertado é por conta tentada, não só por IP.

  1. Cole o widget no formulário — carrega sempre daqui, nunca copiado pro seu servidor:
    <input type="text" name="hp_x7q" data-sentinela-honeypot>
    <div data-sentinela-widget data-sentinela-site="seu-site-slug"></div>
    <input type="hidden" name="sentinela_token" data-sentinela-token>
    <script src="https://sentinela.pangeialabs.com/static/js/sentinela-sdk.js"></script>

    O nome do campo honeypot importa: evite nomes com significado real como empresa, company ou website — autofill e gerenciador de senha do navegador podem preenchê-los para um usuário legítimo, gerando falso positivo. Use um nome curto e sem sentido, como no exemplo.

    data-sentinela-site é o slug do seu site (aparece na URL do painel, /painel/sites/<slug>) — não é segredo, pode ficar visível no HTML. Amarra o desafio resolvido a ESTE site: sem isso, um token resolvido em qualquer lugar valeria pra destravar o /v1/check de qualquer cliente da Sentinela. Opcional por enquanto por retrocompatibilidade (integrações antigas continuam funcionando sem o atributo), mas recomendado pra toda integração nova.

    Atributos opcionais do widget (no <div data-sentinela-widget>; data-sentinela-theme também vale no <script> do SDK, pra todos os widgets da página):

    AtributoEfeito
    data-sentinela-themeauto (padrão), light ou dark. Em auto o widget lê a cor de fundo real da página (claro em site branco, escuro em site escuro; sem fundo detectável, usa o tema do sistema).
    data-sentinela-reset-on-hidefalse desliga: por padrão, se o widget é escondido e reaparece depois de verificado, o token é descartado e o desafio refeito.
    data-sentinela-reset-on-changefalse desliga: por padrão, se qualquer campo do formulário muda depois de verificado, o desafio é refeito.

    Troca de tema com a página aberta: em auto o widget acompanha sozinho — detecta mudança de classe/atributo no <html>/<body> (class="dark", data-theme, data-bs-theme…), do tema do sistema e de troca de CSS (checagem a cada 1s). Se você fixa o tema, pode mudar em tempo real com el.setAttribute('data-sentinela-theme', 'dark').

    Eventos e métodos do widget: o widget mostra sozinho todos os estados (verificando, aguardando gesto, verificado, falhou) e avisa a página, então o formulário não precisa de mensagem própria. Eventos (CustomEvent, sobem pelo DOM): sentinela:token (event.detail.token, quando o token fica válido) e sentinela:expired (token descartado: expirou, campo mudou ou widget reapareceu; o widget já refaz o desafio sozinho). O token também é refeito automaticamente aos 4,5 min, antes de vencer. Método container._sentinelaNudge(): chame no submit sem token para o widget chamar atenção (tremida) em vez de mostrar texto.

    Wizard / modal: “escondido” = display:none no widget ou num ancestral, visibility:hidden ou elemento removido; rolar a página pra fora da tela não conta. O desafio também é refeito se ficou parado perto dos 5 min de validade. Se o wizard só troca de passo com opacidade/transform (sem esconder de fato), chame document.querySelector('[data-sentinela-widget]')._sentinelaRearm() ao entrar no passo do widget.

    Escopo do “mudou um campo”: o <form> que envolve o widget; sem <form>, o elemento-pai direto do widget. Esses resets são conveniência de UX no navegador; quem impõe a validade de verdade é o servidor — o token é de uso único, vale 5 min e é amarrado ao site no /v1/check.

    Cuidado ao customizar o layout: o <input data-sentinela-token> precisa estar no mesmo elemento-pai direto que o <div data-sentinela-widget> — o SDK procura o campo como irmão do widget, não em qualquer lugar do formulário. Se você envolver o widget numa <div> extra (pra alinhar com um botão, por exemplo), mova o campo hidden pra dentro dessa mesma div — senão o token nunca é preenchido e o desafio nunca confirma, sem erro nenhum aparecendo.

  2. No seu backend, ao receber o POST do formulário, chame /v1/check (servidor-a-servidor, com sua API key) antes de checar a senha:
    POST /v1/check
    Authorization: Bearer sk_live_...
    
    {
      "action": "login",
      "identifier": "usuario@dominio.com",
      "honeypot": "<valor do campo isca, deve vir vazio>",
      "challenge_token": "<valor de sentinela_token>",
      "ip": "<IP REAL do visitante>",
      "user_agent": "<User-Agent do visitante (recomendado)>"
    }

    Mande ip sempre, explicitamente. Essa chamada é servidor-a-servidor (seu backend → Sentinela) — se você omitir ip, a Sentinela cai num fallback que só enxerga a conexão ATUAL (seu backend → Sentinela), nunca o navegador do visitante original. Atrás de um proxy reverso/load balancer (o caso comum), isso vira o IP do proxy ou até de um NAT interno, não do visitante — rate limit, geolocalização e evidência de rede ficam todos errados. Capture o IP real na ponta onde você recebe a requisição do visitante (ex.: X-Forwarded-For do seu próprio proxy) e repasse aqui.

    Só navegador de verdade. Se o desafio foi pedido com User-Agent de navegador mas a conexão TLS não é de navegador (cliente HTTP de script se passando por Chrome), ou se o user_agent que você manda não é de navegador, o token não vale: "challenge", com os dados do cliente em evidence.client (User-Agent de quem resolveu, User-Agent que você viu, ALPN e JA4 da conexão).

    O token é de quem resolveu o desafio. Ele só vale se o ip informado estiver na mesma rede do navegador que resolveu (mesmo /24 ou /48, ou mesmo ASN) e, se você mandar user_agent, no mesmo navegador. Senão a decisão é "challenge" com evidence.token_binding: impede resolver o desafio num navegador (ou numa fazenda de captcha) e usar o token num script de outro lugar.

  3. Aja sobre a resposta: {"decision":"allow"} segue o fluxo normal (confere a senha); "challenge" devolve erro genérico pedindo pra repetir o gesto; "block" rejeita sem mais detalhe pro chamador — quando o bloqueio for por limite de tentativas, a resposta inclui "retry_after_seconds" (quantos segundos faltam pra essa conta/IP poder tentar de novo), útil pra mostrar "tente novamente em X min" em vez de um erro genérico.

Camadas internas do widget (prova de trabalho, sinal de automação do navegador) rodam automaticamente dentro do sentinela-sdk.js — não exigem nada do seu lado além de já estar usando o widget.

Limites atuais (ajustáveis conforme o ataque evoluir — sem precisar mudar nada no seu lado): login, 6 tentativas/10min por conta e 15/10min por IP; cadastro, 3/hora por identificador e 20/hora por IP; recuperação de senha (action: "recover"), contador próprio de 3/hora por identificador e 5/hora por IP. Toda chamada ao /v1/check conta como tentativa no limite — inclusive as que já voltaram block (insistir durante um bloqueio adia a liberação). Sem identifier na chamada, só o limite por IP é aplicado.

Confiança e evidência (nunca só um sim/não)

Toda resposta de /v1/check também traz confidence (0–100) e evidence — os sinais que embasaram a decisão (velocidade observada, nível do desafio resolvido, metadados da conexão TLS, se alguma regra sua bateu). Use isso pra registrar/depurar, não só o decision puro:

{
  "decision": "allow",
  "reason": "sinais consistentes com humano",
  "confidence": 75,
  "evidence": {
    "honeypot": false,
    "velocity_global": 3,
    "challenge_tier": 2,
    "tls": { "tls_version": "tls1.3", "tls_cipher": "TLS_AES_128_GCM_SHA256", "tls_alpn": "h2" }
  }
}

Regras próprias (allow/challenge/block/log)

Cadastre regras que têm prioridade sobre qualquer sinal automático — ex.: liberar o IP do seu escritório, ou banir um identificador específico depois de uma fraude confirmada. Gerencie em /painel, aba "Regras" do seu site: tipo de regra e o campo de valor mudam juntos (com dica do que preencher), dá pra editar uma regra existente no lugar (sem precisar apagar e recriar — uma regra de block continua protegendo enquanto você corrige um typo), a tabela mostra a ordem de avaliação (checadas de cima pra baixo, a primeira ativa que bater decide) e quantas vezes cada regra já bateu. Confirmação extra ao criar/editar regra de challenge/block, e aviso se a faixa CIDR for muito ampla ou se já existir uma regra idêntica. Tipos: ip, ip_range (CIDR), identifier_exact, identifier_domain, asn, country, network_type (datacenter, cloud, cdn, tor ou vpn), user_agent_pattern (regex), device_fingerprint (hash exato — bane um aparelho específico permanentemente). Ações: allow/challenge/block decidem de verdade; log nunca decide nada, só registra que bateria — modo monitor pra testar uma regra nova antes de promovê-la (mesma recomendação que a Cloudflare dá pra WAF Custom Rules). Negar (checkbox "negar" na UI) inverte a condição — bate quando o valor NÃO for o cadastrado: country ≠ BR com ação block bloqueia qualquer país que não seja Brasil, com uma regra só, em vez de cadastrar ~195 países individualmente. Negação de country/asn/network_type/user_agent_pattern/device_fingerprint só é avaliada depois que o desafio resolve (mesmo motivo dos _LATE_KINDS acima — sem isso "ainda sem dado" seria confundido com "diferente de X", bloqueando 100% do tráfego cedo demais); país desconhecido (geolocalização falhou) também bate numa regra negada, por segurança (geo-bloqueio estrito: exige prova de que É o país permitido). Negação de identifier_exact/identifier_domain só bate se houver um identifier de verdade na tentativa.

Feedback (fecha o loop do Risk Engine)

Depois de descobrir que uma tentativa era fraude (ou era legítima), avise — isso alimenta a recalibração futura do modelo de confiança:

POST /v1/feedback
Authorization: Bearer sk_live_...

{ "identifier": "usuario@dominio.com", "was_fraud": true, "note": "chargeback confirmado" }

Canal de contestação (falso positivo)

Toda resposta de /v1/check traz um reference_id — guarde isso no seu log. Quando um usuário reclamar que foi bloqueado indevidamente, seu suporte consulta essa tentativa específica:

GET /v1/attempts/<reference_id>?identifier=usuario@dominio.com
Authorization: Bearer sk_live_...

identifier é obrigatório e precisa ser o mesmo da tentativa original — sem isso não devolve nada (proteção contra enumerar tentativas de outros usuários seus). Devolve toda a evidência daquela tentativa (rede, TLS/JA3-JA4, comportamento) pra você entender o "porquê". Se confirmar que foi falso positivo, a reversão é a mesma regra que já existe: cadastre uma regra identifier_exact com ação allow pra esse usuário (ver seção "Regras próprias" acima). Isto é uma ferramenta pro seu suporte investigar, não um canal direto pro usuário final — mesmo padrão que Cloudflare (Ray ID) e Akamai (reference number) usam: o vendor de anti-bot não tem relação com o visitante final, só com o site que ele protege.

Webhook de atualização de risco no meio da sessão

É opcional — a integração (widget + /v1/check) funciona sem ele. A URL que você cadastra é de um endpoint do seu próprio backend (ex.: https://seuapp.com/webhooks/sentinela), que a Sentinela chama; não é uma URL da Sentinela. Só vale configurar se o seu app for reagir ao aviso (derrubar a sessão, pedir verificação extra).

Opt-in — configure em /painel, na aba "Configurações" do seu site (tem botão de "enviar evento de teste" pra conferir antes de depender disso em produção, limitado a poucos disparos por minuto). A URL precisa ser http:///https:// e não pode apontar pra endereço interno/privado — checamos isso na hora de salvar e de novo a cada envio. Seu endpoint precisa responder direto, sem redirecionar (3xx é tratado como falha de entrega, nunca seguido) — isso é proteção nossa contra abuso, não uma limitação arbitrária. Quando o ambiente do visitante muda entre o carregamento do widget e o gesto de confirmação (ex.: navigator.webdriver ligando no meio do caminho), mandamos um POST assinado pro seu webhook_url:

POST <seu webhook_url>
Content-Type: application/json
X-Sentinela-Signature: sha256=<hmac-sha256 do corpo com seu secret>

{
  "event": "risk_changed_mid_session",
  "site_slug": "seu-site",
  "identifier": "usuario@dominio.com",
  "flags": ["webdriver_ligou_durante_sessao"],
  "challenge_token": "...",
  "ts": "2026-09-29T00:00:00+00:00"
}

Verifique a assinatura antes de confiar no corpo (mesmo esquema HMAC-SHA256 que usamos pra assinar webhooks do PANGEIA ID/PAY). Fire-and-forget do nosso lado — se seu endpoint estiver fora do ar, isso nunca afeta o /v1/check. Cobertura atual: só a janela entre o carregamento do widget e o gesto, não é monitoramento contínuo depois do allow.

O secret aparece uma única vez, quando você salva a URL — guarde na hora. Salvar uma URL nova gera um secret novo (o anterior deixa de valer). Calcule o HMAC sobre o corpo cru da requisição (os bytes recebidos, antes de parsear o JSON) e compare em tempo constante:

JavaScript (Node / Express)
const crypto = require("crypto");
// use express.raw({ type: "application/json" }) nesta rota pra ter o corpo cru
app.post("/webhooks/sentinela", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.SENTINELA_WEBHOOK_SECRET)
    .update(req.body).digest("hex");
  const got = req.get("X-Sentinela-Signature") || "";
  const ok = got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);
  const evt = JSON.parse(req.body);
  // evt.event === "risk_changed_mid_session" -> aja sobre evt.identifier
  res.sendStatus(200); // responda direto, sem redirecionar
});
Python (Flask)
import hmac, hashlib

@app.post("/webhooks/sentinela")
def sentinela_webhook():
    body = request.get_data()  # corpo cru
    expected = "sha256=" + hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(request.headers.get("X-Sentinela-Signature", ""), expected):
        return "", 401
    evt = request.get_json()
    # evt["event"] == "risk_changed_mid_session" -> aja sobre evt["identifier"]
    return "", 200

1)Fluxo de integração

Toda avaliação de risco segue o mesmo caminho, em 3 chamadas (ver o passo a passo completo na seção "0" acima):

  1. POST /v1/challenge/new — chamado DIRETO pelo navegador do visitante (nunca pelo seu backend), pelo sentinela-sdk.js. Recebe os sinais coletados no navegador (ambiente, fingerprint) e devolve um token + o nível do Challenge Engine decidido pro visitante (0 invisível, 1 prova de trabalho, 2 gesto).
  2. POST /v1/challenge/verify — também do navegador, chamado pelo SDK quando o visitante resolve o desafio (ou automaticamente, no nível 0). Confirma o resultado e marca o token como pronto pra ser resgatado.
  3. POST /v1/check — do SEU backend (servidor-a-servidor, com sua API key), no momento do submit de verdade (login/cadastro). Resgata o token, correlaciona tudo (rede, TLS, comportamento, regras próprias) e devolve evidência estruturada com confidence (0–100) e a decision (allow/challenge/block). A Sentinela nunca decide por você — sua aplicação age sobre essa resposta com a própria política.

Endpoints de Network Intelligence e Email Intelligence funcionam à parte, como consulta direta (você manda um IP, domínio ou e-mail, recebe o perfil completo), sem depender de uma sessão de visitante.

2)Autenticação

Toda chamada leva sua chave de API no cabeçalho Authorization. Existem chaves de test (sk_test_..., não conta pro seu uso faturável) e de live (sk_live_...). Gerencie as suas em /painel, aba "Configurações" do site — cada site tem uma chave por modo (live e test), valendo pro site todo. Pra trocar, use "regenerar chave" — a atual é revogada na hora e a nova aparece uma única vez, então atualize sua integração logo em seguida. Revogar manualmente exige digitar o identificador do site pra confirmar, e recusa por padrão revogar a última chave live ativa (precisa de uma segunda confirmação explícita). Excluir o site (aba "Configurações" → "Zona de perigo", também com confirmação digitada) revoga todas as chaves e desativa a integração imediatamente.

Authorization: Bearer sk_live_51a2b3c4d5e6f7...

3)Endpoints principais

MétodoEndpointAuthUso
POST/v1/challenge/newpública (CORS)Navegador do visitante pede um desafio novo — nível 0/1/2 decidido pelo servidor
POST/v1/challenge/verifypública (CORS)Navegador confirma o resultado do desafio (gesto/PoW)
POST/v1/checkAPI keySeu backend resgata o token e recebe a decisão (allow/challenge/block)
POST/v1/feedbackAPI keyFecha o loop: avisa se uma tentativa era fraude de verdade ou não
GET/v1/attempts/<id>API keyCanal de contestação — consulta a evidência completa de uma tentativa específica
POST/v1/lookupAPI keyConsulta direta de IP e/ou e-mail: listas, histórico e recomendação
GET/v1/network/lookupAPI keyNetwork + Intermediary Intelligence de um IP
POST/v1/email/lookupAPI keyEmail Intelligence de um domínio ou endereço

4)POST /v1/check — referência completa

POST/v1/check

Chamado pelo SEU backend, servidor-a-servidor, no momento do submit de verdade (ver passo a passo na seção "0"). Corpo completo:

{
  "action": "login",
  "identifier": "usuario@dominio.com",
  "honeypot": "",
  "challenge_token": "<token devolvido por /v1/challenge/new>",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 ..."
}

action aceita "login", "signup" ou "recover" (qualquer outra devolve 400) — cada uma tem seu próprio limite de tentativas (ver seção "0"). identifier é o que o visitante está tentando autenticar (e-mail, user id) — entra na correlação de velocidade por conta, não só por IP.

Resposta:

{
  "decision": "allow",
  "reason": "sinais consistentes com humano",
  "confidence": 75,
  "evidence": {
    "honeypot": false,
    "ip_is_private": false,
    "velocity_global": 3,
    "challenge_tier": 2,
    "tls": { "tls_version": "tls1.3", "tls_cipher": "...", "ja3": "...", "ja4": "..." },
    "device": { "fingerprint_seen_before": false, "times_seen": 1, "seen_on_other_sites": 0 },
    "network": { "country": "BR", "asn_name": "...", "datacenter": false, "cloud_provider": null, "cdn": null, "tor_exit": false, "threat_score": 0 }
  },
  "reference_id": "65f1a2b3c4d5e6f7a8b9c0d1"
}

evidence só inclui os campos que já existem naquele ponto da avaliação (uma decisão block por rate limit, por exemplo, nunca chega a ter network/device — a chamada decide cedo, antes de gastar essas consultas). Quando o identifier é um e-mail de domínio descartável/temporário ou mascarado, vem evidence.email ({"domain", "type": "disposable"|"masked", "matched", "via"}). No signup, e-mail descartável é bloqueado (decision: "block", reason começando com "e-mail descartável/temporário"). A lista de domínios é mantida pela PANGEIA, alimentada por fonte pública e pela detecção do MX (domínio novo cujo MX é de serviço descartável entra sozinho). IP em faixa bloqueada pela PANGEIA por abuso confirmado traz evidence.blocked_range. Suas regras rodam antes das duas coisas, então uma regra allow sua libera um domínio ou IP específico. Visitante de país fora do Brasil, de país desconhecido ou vindo de saída Tor/CDN sempre recebe o desafio completo (prova de trabalho + gesto); se o ip que você manda no /v1/check cair nesse caso e o token for de nível mais leve, a resposta é challenge com evidence.origin_requires_full_challenge explicando o motivo. Por isso, sempre mande o IP real do visitante. reference_id é o <id> que você usa depois em GET /v1/attempts/<id> (canal de contestação, ver seção "0").

POST /v1/challenge/new / POST /v1/challenge/verify

Chamados pelo sentinela-sdk.js, direto do navegador do visitante — você não integra com eles diretamente na maioria dos casos (o widget cuida disso). Documentados aqui pra quem está construindo uma integração customizada sem o SDK padrão:

POST /v1/challenge/new
{ "signals": { ... }, "site_slug": "seu-site-slug" }

→ { "token": "...", "tier": 2, "pow_seed": "...", "pow_bits": 18 }

POST /v1/challenge/verify
{ "token": "...", "held_ms": 1180, "pow_nonce": "...", "webdriver": false }

→ { "ok": true, "reason": null }

site_slug é o mesmo data-sentinela-site da seção "0" — amarra o desafio a um site específico, evitando que um token farmado em outro lugar valha pra destravar o seu /v1/check.

5)POST /v1/email/lookup — inteligência de e-mail/domínio

POST/v1/email/lookup
{ "domain": "exemplo.com.br" }

Aceita domain ou email (extrai o domínio). Resposta — configuração de e-mail (MX/SPF/DMARC, motor já usado desde a Fase 0) e WHOIS + Network/Intermediary Intelligence de cada IP associado ao MX:

{
  "domain": "exemplo.com.br",
  "mx": [{ "host": "aspmx.l.google.com", "pref": 1, "ips": [...] }],
  "spf": "v=spf1 include:_spf.google.com ~all",
  "dmarc": { "policy": "quarantine", "pct": 100 },
  "whois": { "registrar": "...", "created_at": "...", "age_days": 4021 },
  "mx_network": [
    { "ip": "142.250.x.x", "country": "US", "asn_name": "GOOGLE",
      "datacenter": true, "cloud_provider": "Google Cloud", "cdn": null, "tor_exit": false, "vpn_proxy": "unknown" }
  ]
}

5.0)POST /v1/lookup — consulta direta de IP e/ou e-mail

POST/v1/lookup

Para fluxos sem widget (API própria, app, fila de moderação, revisão de cadastro já feito): pergunte ao Sentinela o que ele sabe de um IP, de um e-mail ou dos dois. Não grava tentativa e não conta no limite de tentativas.

{ "ip": "203.0.113.7", "email": "usuario@dominio.com" }

Resposta:

{
  "ip": {
    "ip": "203.0.113.7",
    "network": { "country": "NL", "asn_name": "...", "datacenter": true, "cloud_provider": null,
                 "cdn": null, "tor_exit": false, "vpn_proxy": "unknown", "blocked_range": null, "threat_score": 0 },
    "requires_full_challenge": "origem fora dos países liberados (NL)",
    "history": { "days": 30, "all_sites": { "allow": 3, "challenge": 1, "block": 9 },
                 "this_site": { "allow": 0, "challenge": 0, "block": 2 },
                 "other_sites_count": 3, "last_seen": "2026-11-03T07:23:48+00:00" }
  },
  "email": {
    "email": "usuario@dominio.com", "domain": "dominio.com",
    "type": null, "matched": null, "via": null,
    "history": { "days": 30, "all_sites": { "allow": 0, "challenge": 0, "block": 0 }, "...": "..." }
  },
  "recommendation": {
    "decision": "challenge",
    "reasons": ["desafio completo obrigatório: origem fora dos países liberados (NL)", "9 bloqueio(s) desse IP nos últimos 30 dias"]
  }
}

email.type: "disposable" (descartável/temporário), "masked" (alias de privacidade) ou null. history conta as decisões do Sentinela para esse IP/e-mail em todos os sites que usam o Sentinela e só no seu, sem nunca dizer quais são os outros sites. recommendation aplica as listas da PANGEIA e a política do seu site, como o /v1/check faria. A decisão final é sua.

5.1)GET /v1/network/lookup — inteligência de rede de um IP

GET/v1/network/lookup?ip=203.0.113.7
{
  "ip": "203.0.113.7",
  "country": "BR",
  "asn_name": "...",
  "datacenter": false,
  "cloud_provider": null,
  "cdn": null,
  "tor_exit": false,
  "vpn_proxy": "unknown",
  "threat_score": 0,
  "dataset_meta": {
    "tor_exit_list": { "source": "...", "last_updated": "..." }
  }
}

vpn_proxy traz o nome do provedor quando o IP está nas listas de servidores que os próprios provedores de VPN publicam (Mullvad, NordVPN, IVPN, Windscribe, PIA…). Fora delas vem "unknown", e unknown ≠ false: não afirmamos "não é VPN". Visitante vindo de VPN conhecida sempre recebe o desafio completo. threat_score é evidência de PRIMEIRA MÃO: esse IP já atacou a própria infra da PANGEIA. A PANGEIA não usa blacklist de terceiros. As únicas fontes externas são as listas que o Tor Project e os provedores de cloud/CDN publicam sobre a própria infraestrutura. dataset_meta existe pra transparência: de onde vem cada classificação e quando foi atualizada, nunca uma caixa-preta.

6)Exemplos de código

cURL
curl -X POST https://sentinela.pangeialabs.com/v1/check \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"action":"login","identifier":"usuario@dominio.com","honeypot":"","challenge_token":"...","ip":"203.0.113.42"}'
JavaScript (Node)
const r = await fetch("https://sentinela.pangeialabs.com/v1/check", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.SENTINELA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action: "login", identifier: email, honeypot: req.body.hp_x7q,
    challenge_token: req.body.sentinela_token, ip: realVisitorIp,
    user_agent: req.headers["user-agent"],
  }),
});
const result = await r.json();
if (result.decision === "block") { /* rejeite, mostre result.reason se útil */ }
Python
import requests

r = requests.post(
    "https://sentinela.pangeialabs.com/v1/check",
    headers={"Authorization": f"Bearer {SENTINELA_API_KEY}"},
    json={
        "action": "login", "identifier": email, "honeypot": request.form.get("hp_x7q", ""),
        "challenge_token": request.form.get("sentinela_token"), "ip": real_visitor_ip,
    },
)
result = r.json()

7)SDK JavaScript (client-side)

<div data-sentinela-widget data-sentinela-site="seu-site-slug"></div>
<script src="https://sentinela.pangeialabs.com/static/js/sentinela-sdk.js"></script>

O SDK coleta os sinais no navegador e injeta o widget do Challenge Engine (invisível na maioria das vezes) automaticamente — ver os 4 níveis de escalada na página do produto. data-sentinela-site é opcional (retrocompatibilidade) mas recomendado — ver detalhe na seção "0".

8)Webhooks

Configure em /painel → seu site → "Configurações" (detalhes e formato completo do payload na seção acima). Eventos disparados hoje:

EventoQuando dispara
risk_changed_mid_sessionSession Intelligence detecta mudança de ambiente entre o carregamento do widget e o gesto de verificação
testBotão "enviar evento de teste" no painel — pra você conferir que seu endpoint recebe e valida a assinatura antes de depender disso em produção

Validação via cabeçalho X-Sentinela-Signature (HMAC-SHA256), mesmo padrão do Pangeia ID.

9)Códigos de status

Cobrança por plano ainda não tem limite técnico aplicado na API (uso acima do plano não derruba chamada nenhuma hoje) — acompanhe consumo em faturamento por ora.

10)Arquivos oficiais

OpenAPI 3: /apidoc/openapi.yaml (importe no Postman/Insomnia ou gere cliente) · Roadmap público do produto: página inicial