Documentação do Prynt Gate

Referência da API

URL base `https://api.pryntid.com`. JSON em camelCase; a entrada de eventos também aceita snake_case.

Autenticação

Authorization: Bearer <token> com um token de sensor (gk_<env>_…, restrito a /v1/gate/* daquele sensor) ou a chave secreta do ambiente (sk_<env>_…, com sensor no corpo; um nome novo registra o sensor).

StatusSignificado
401 unauthorizedtoken inválido ou sensor desativado
402 product_requireda conta não tem plano do Gate
413 payload_too_largecorpo acima de 1 MB
422 validation_errorcorpo malformado
429 rate_limited · quota_exceeded600 requisições/min por sensor, ou eventos do mês esgotados

POST /v1/gate/events

Até 500 eventos por requisição, como {sensor, events: […]}, um array JSON ou NDJSON. Idempotente por eventId (derivado do evento quando ausente).

POST https://api.pryntid.com/v1/gate/events
Authorization: Bearer gk_live_YOUR_SENSOR_TOKEN
Content-Type: application/json

{
  "sensor": "gps-01",
  "events": [{
    "eventId": "tr-5027-0001",
    "ts": "2026-11-15T18:02:11Z",
    "host": "gps-gateway",
    "port": 5027,
    "protocol": "teltonika",
    "transport": "tcp",
    "srcIp": "203.0.113.7",
    "srcPort": 51234,
    "claimedIdentity": {"type": "imei", "value": "356307042441013"},
    "outcome": "unknown_id",
    "metadata": {"parser": "traccar"}
  }]
}
CampoNotas
srcIpobrigatório; IPv4 ou IPv6
tsISO 8601 ou epoch (s ou ms); padrão: hora do recebimento
claimedIdentity{type, value}: imei, panel_account, username, email, ssh_key_fp, turn_user, device_id, mac, other…
port · protocol · transportporta local, nome do protocolo, tcp ou udp
metadataobjeto livre de até 4 KB (payloadPrefix alimenta o detector de scanners)
`outcome`Significado
connectsessão TCP/UDP aberta
auth_oka identidade declarada foi aceita
auth_failsenha, chave ou assinatura incorreta
unknown_ida identidade não existe no seu servidor
disconnectsessão encerrada
data · errortráfego ou erro de protocolo em uma sessão aberta

Resposta:

{
  "accepted": 1, "duplicates": 0, "rejected": [],
  "decisions": [{"eventId": "tr-5027-0001", "decision": "block", "score": 90,
                 "reasons": ["enumeration:6"], "srcIp": "203.0.113.7"}],
  "blocks": [{"id": 12, "ip": "203.0.113.7", "expiresAt": "2026-11-15T19:02:11Z", "reason": "enumeration"}]
}

decisions lista apenas os eventos sinalizados ou bloqueados. Cada evento aceito conta um da cota mensal.

POST /v1/gate/logs

Linhas de log brutas, processadas no servidor: veja Fontes de logs.

GET /v1/gate/blocks

A lista completa de bloqueios ativos para o bouncer, o modo do sensor e a lista de permissões. version só muda quando a lista muda.

GET https://api.pryntid.com/v1/gate/blocks
Authorization: Bearer gk_live_YOUR_SENSOR_TOKEN

{
  "mode": "enforce",
  "blocks": [{"id": 12, "ip": "203.0.113.7", "reason": "enumeration",
              "expiresAt": "2026-11-15T19:02:11Z", "createdAt": "2026-11-15T18:02:11Z"}],
  "allowlist": ["192.168.1.0/24", "10.0.0.1/32"],
  "version": "b3f1…",
  "serverTime": "2026-11-15T18:05:00Z"
}

POST /v1/gate/heartbeat

POST https://api.pryntid.com/v1/gate/heartbeat
Authorization: Bearer gk_live_YOUR_SENSOR_TOKEN

{"agentVersion": "0.1.0", "hostname": "gps-gateway", "mode": "dry_run", "backend": "nftables",
 "appliedBlocks": 3, "parsers": ["traccar"], "spooled": 0}

Detectores e pontuação

Cada evento é enriquecido offline (país, cidade, ASN e operadora, VPN, hosting, Tor, listas de abuso) e passa por estes detectores. Limites, janelas e ações são editáveis em Gate → Configurações.

DetectorDispara quandoPadrão
enumerationuma origem tenta ≥ 5 identidades desconhecidas em 10 minblock
authFailBurst≥ 10 falhas de autenticação de uma origem em 5 minblock
identityAuthFail≥ 5 falhas contra uma mesma identidade em 10 minflag
concurrentSourcesa mesma identidade conectada de 2+ origens ao mesmo tempoflag
newAsn · newCountryuma identidade vista de uma rede ou país novoflag
impossibleTravel> 900 km/h entre dois locais a mais de 500 kmflag
firstSeenuma identidade nunca vistasinal
portScanuma origem toca ≥ 4 portas em 10 minblock
scannerredes de scanners conhecidas, payloads de scanner, listas de abusoflag
torOrHostinguma identidade de equipamento (IMEI, conta de painel) de Tor, VPN ou hostingflag
identityBlockeduma identidade que você marcou como bloqueadablock

A pontuação vai de 0 a 100 com os motivos que a compõem: block a partir de 80 ou quando um detector ou regra bloqueia, flag a partir de 40. Um IP da lista de permissões é sempre allow (os sinais são registrados mesmo assim).

Regras

As mesmas regras declarativas do Identify: um campo, um operador (eq, ne, gt, lt, gte, lte, in), um valor e uma ação (allow, flag, block), por prioridade; o modo evaluate só conta as correspondências. Campos: idType, outcome, port, protocol, sensor, country, asn, asnType, vpn, tor, hosting, firstSeen, newAsn, newCountry, concurrentSources, unknownIdsFromSource, authFailsFromSource, distinctPortsFromSource, travelKmh, riskScore e identityStatus.

{"name": "Connection from a datacenter", "field": "asnType", "op": "eq", "value": "hosting", "action": "block", "priority": 10}
{"name": "Stricter enumeration", "field": "unknownIdsFromSource", "op": "gte", "value": "3", "action": "block", "priority": 20}
{"name": "Alarm panel abroad", "field": "newCountry", "op": "eq", "value": "true", "action": "flag", "priority": 30}

Uma decisão block bloqueia o IP de origem por blockTtlMinutes (60 por padrão; uma regra pode definir o seu). IPs permitidos e privados nunca são bloqueados automaticamente.

Registro à prova de adulteração

Cada evento leva seq, prevHash e hash = sha256(prevHash + JSON canônico do evento e da decisão), uma cadeia por conta e ambiente. Não há API para editar nem apagar eventos. A retenção remove os mais antigos e deixa um ponto de controle; a verificação do registro no console (GET /admin/gate/log/verify) recalcula a cadeia.

Webhooks

Inscreva um endpoint em Webhooks em gate.decision, gate.block.created, gate.block.revoked ou gate.alert. As entregas são assinadas como todo webhook da Prynt: X-Prynt-Signature: sha256=HMAC(segredo, "<X-Prynt-Timestamp>." + corpo).

{
  "type": "gate.decision",
  "createdAt": "2026-11-15T18:02:12Z",
  "data": {"eventId": "tr-5027-0001", "decision": "flag", "score": 70,
           "reasons": ["concurrentSources:2"], "identity": {"type": "imei", "value": "356307042441013"},
           "srcIp": "198.51.100.23", "port": 5027, "sensor": "gps-01"}
}
// Node.js: verify X-Prynt-Signature (same scheme as every Prynt webhook)
import crypto from 'node:crypto';

function verify(rawBody, headers, secret) {
  const ts = headers['x-prynt-timestamp'];
  const sig = (headers['x-prynt-signature'] || '').replace('sha256=', '');
  const want = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

Próximo: Exemplo: GPS e alarmes

Atualizado 2026-11-15 · Referência da API