PAT

Autenticación

Las rutas de integración usan un token de acceso personal (PAT) en Authorization: Bearer. El JWT de sesión del navegador no sirve para extract, ingest ni retest.

Formato del token

eva_pat_<secreto>

Prefijo literal: eva_pat_.
El secreto es aleatorio (32+ bytes, urlsafe).
EVA muestra el valor completo una sola vez al crearlo. Después solo verá un prefijo (eva_pat_xxxx).
Pertenece a un user_id + tenant_id.
Caducidad por defecto 90 días (1–365). Máximo 5 tokens activos por usuario/tenant.
allowed_cidrs opcional (máx. 16 redes IPv4/IPv6). Vacío = cualquier IP. Solo se fija al crear: si cambia la IP, revoque el PAT y cree otro. La allowlist se aplica a extract/ingest, no a retest. Rangos en notación CIDR (10.0.0.0/8), no con guion. Una IP: 127.0.0.1/32.
Revocación inmediata: un PAT revocado o caducado deja de autenticar. El runner vivo pasa a /ready 503 y backoff auth_failed (~60 s); no martilla pending cada 15 s.

No reutilice un JWT de sesión (typ=access) como PAT de integración.

Scopes

Al menos uno es obligatorio. ingest puede ser el único alcance.

Scope	Valor JSON	Uso
Extract	`extract`	`GET …/reports/index`, `GET …/reports/extract` y `POST …/reports/extract-batch`. No autentica ingest ni retest.
Ingest	`ingest`	Ensure de proyecto y JSON/CSV de hallazgos o aspectos. Puede ser el único alcance.
Retest lectura	`retest_read`	`GET …/retests/pending`
Retest escritura	`retest_write`	`POST …/claim`, `heartbeat`, `result`

El runner de producto usa los dos: retest_read + retest_write.
PAT solo-extract contra ingest o retest → 403 INTEGRATION_SCOPE_DENIED.
PAT con retest_read pero sin retest_write puede hacer pending; claim/heartbeat/result → 403.
Si omite scopes al crear, el default sigue siendo ["extract"].

Cómo crear un token

Inicie sesión en EVA.
Abra Cuenta → Configuración y la pestaña Integración.
Cree un token con un nombre reconocible y los alcances que necesita.
Copie el secreto en ese momento. EVA no lo vuelve a mostrar.
Úselo solo como Authorization: Bearer. Nunca en la URL ni en query string.

Para rotar: cree un token nuevo, actualice el cliente, revogue el anterior. Máximo 5 tokens activos. Caducidad por defecto 90 días (1–365).

Al crear puede indicar allowed_cidrs (hasta 16 redes). Vacío = cualquier IP. Si cambia la red, revogue y cree otro. CIDR inválido → 422.

Cabeceras de integración

Directo al backend. El tenant sale del PAT, no del host.

Cabecera	Obligatorio	Valor
`Authorization`	Sí	`Bearer eva_pat_<secreto>`
`X-Tenant-Id`	No	UUID del tenant. Si se envía, debe coincidir con el tenant del PAT.
`Accept`	Recomendado	`application/json`
`Content-Type`	En POST JSON	`application/json`

Un X-Tenant-Id distinto al tenant del token → 403 TENANT_MISMATCH. No envíe cookies de sesión. No envíe el PAT en query string, logs, tickets ni repositorios.

Seguridad

Guarde el PAT en un almacén de secretos. Nunca en git, tickets, capturas ni variables de CI en claro.
Rótalo al cambiar de sistema destino, al sospechar filtración, o al acercarse la caducidad.
Use HTTPS. El JSON de extract contiene hallazgos en claro.
Revogue de inmediato tokens que ya no use.
Si restringe origen, liste las redes del cliente en allowed_cidrs al crear. Extract/ingest fuera de esas redes responden 403 INTEGRATION_IP_DENIED. Retest no usa esta lista.
Laboratorio: deje allowed_cidrs vacío. Si restringe, use notación CIDR (10.0.0.0/8).
No reenvíe el body de extract a logs de aplicación. EVA tampoco lo registra.