Autenticación
Authorization: Bearer <token> con un token de sensor (gk_<env>_…, limitado a /v1/gate/* de ese sensor) o la clave secreta del entorno (sk_<env>_…, con sensor en el cuerpo; un nombre nuevo da de alta el sensor).
| Estado | Significado |
|---|---|
401 unauthorized | token inválido o sensor desactivado |
402 product_required | la cuenta no tiene plan de Gate |
413 payload_too_large | cuerpo de más de 1 MB |
422 validation_error | cuerpo mal formado |
429 rate_limited · quota_exceeded | 600 peticiones/min por sensor, o eventos del mes agotados |
POST /v1/gate/events
Hasta 500 eventos por petición, como {sensor, events: […]}, un array JSON o NDJSON. Idempotente por eventId (se deriva del evento si falta).
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"}
}]
}| Campo | Notas |
|---|---|
srcIp | obligatorio; IPv4 o IPv6 |
ts | ISO 8601 o epoch (s o ms); por defecto, la hora de recepción |
claimedIdentity | {type, value}: imei, panel_account, username, email, ssh_key_fp, turn_user, device_id, mac, other… |
port · protocol · transport | puerto local, nombre del protocolo, tcp o udp |
metadata | objeto libre de hasta 4 KB (payloadPrefix alimenta el detector de escáneres) |
| `outcome` | Significado |
|---|---|
connect | sesión TCP/UDP abierta |
auth_ok | la identidad declarada fue aceptada |
auth_fail | contraseña, clave o firma incorrecta |
unknown_id | la identidad no existe en tu servidor |
disconnect | sesión cerrada |
data · error | tráfico o error de protocolo en una sesión abierta |
Respuesta:
{
"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 solo lista los eventos marcados o bloqueados. Cada evento aceptado cuenta uno de la cuota mensual.
POST /v1/gate/logs
Líneas de log en crudo, procesadas en el servidor: ver Fuentes de logs.
GET /v1/gate/blocks
La lista completa de bloqueos activos para el bouncer, el modo del sensor y la lista de permitidos. version solo cambia cuando cambia la lista.
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 y puntuación
Cada evento se enriquece sin conexión externa (país, ciudad, ASN y su operador, VPN, hosting, Tor, listas de abuso) y pasa por estos detectores. Umbrales, ventanas y acciones se editan en Gate → Ajustes.
| Detector | Se activa cuando | Por defecto |
|---|---|---|
enumeration | un origen prueba ≥ 5 identidades desconocidas en 10 min | block |
authFailBurst | ≥ 10 fallos de autenticación desde un origen en 5 min | block |
identityAuthFail | ≥ 5 fallos contra una misma identidad en 10 min | flag |
concurrentSources | la misma identidad conectada desde 2+ orígenes a la vez | flag |
newAsn · newCountry | una identidad vista desde una red o país nuevo | flag |
impossibleTravel | > 900 km/h entre dos ubicaciones a más de 500 km | flag |
firstSeen | una identidad nunca vista | señal |
portScan | un origen toca ≥ 4 puertos en 10 min | block |
scanner | redes de escáneres conocidas, cargas de escáner, listas de abuso | flag |
torOrHosting | una identidad de equipo (IMEI, cuenta de panel) desde Tor, VPN o hosting | flag |
identityBlocked | una identidad que marcaste como bloqueada | block |
La puntuación va de 0 a 100 con los motivos que la forman: block desde 80 o cuando un detector o regla bloquea, flag desde 40. Una IP de la lista de permitidos siempre es allow (sus señales se registran igual).
Reglas
Las mismas reglas declarativas que Identify: un campo, un operador (eq, ne, gt, lt, gte, lte, in), un valor y una acción (allow, flag, block), por prioridad; el modo evaluate solo cuenta coincidencias. 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}Una decisión block bloquea la IP de origen durante blockTtlMinutes (60 por defecto; una regla puede fijar el suyo). Las IPs permitidas y las privadas nunca se bloquean automáticamente.
Registro inalterable
Cada evento lleva seq, prevHash y hash = sha256(prevHash + JSON canónico del evento y su decisión), una cadena por cuenta y entorno. No hay API para editar ni borrar eventos. La retención borra los más antiguos y deja un punto de control; la verificación del registro en la consola (GET /admin/gate/log/verify) recalcula la cadena.
Webhooks
Suscribe un endpoint en Webhooks a gate.decision, gate.block.created, gate.block.revoked o gate.alert. Los envíos se firman como todos los webhooks de Prynt: X-Prynt-Signature: sha256=HMAC(secreto, "<X-Prynt-Timestamp>." + cuerpo).
{
"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));
} Siguiente: Ejemplo: GPS y alarmas
Actualizado 2026-11-15 · Referencia de la API