Autenticación — Agent token
Cada request al Agent API público necesita una sola cosa:
Authorization: Bearer <agent-token>
El agent token es un string hex de 64 caracteres sin prefijo, generado por bench-up.sh en el primer boot (openssl rand -hex 32) e impreso en su banner. Es el mismo token que el CLI guarda en ~/.whet/config.json y que los MCP clients llevan en su header Authorization.
Sin signing secret HMAC, sin keys
pk_live_*/pk_test_*, sin firmas por request. Solo el Bearer token. El esquema HMAC que existe en el codebase (INTERNAL_HMAC_SECRET,WEBHOOK_SIGNING_SECRET) es para el canal internowhet-app↔ backend y los receivers de webhooks entrantes — no se usa en el Agent API público.
Lifecycle del token
| Fase | Qué pasa |
|---|---|
| Generación | bench-up.sh corre openssl rand -hex 32 y escribe el token en el .env.local del workbench como AGENT_API_TOKEN. |
| Distribución | whet auth login del CLI lo guarda en ~/.whet/config.json (permisos 600). Los MCP clients lo llevan en su JSON de config. |
| Rotación | Regenerá AGENT_API_TOKEN en .env.local y reiniciá el container whet-app. El token viejo deja de verificar apenas el container reinicia; no hay ventana de overlap hoy. |
| Revocación | Seteá AGENT_API_TOKEN a un valor nuevo (o vacío) y reiniciá. El token es único — no hay superficie de API-key por cliente todavía. |
Scopes
Hoy el agent token tiene scope completo del workspace. No hay tokens por scope (org:read, artifacts:publish, etc.) — eso es roadmap.
Operacionalmente significa: si no querés que un agente publique, no le des un token. Usá MCP clients en flujos donde el paso de publish siga pasando por un humano confirmando el call.
Errores comunes
| HTTP | error.code | Causa |
|---|---|---|
401 | unauthorized | Header Authorization ausente, token incorrecto, o AGENT_API_TOKEN no seteado en el server. |
403 | forbidden | El token es válido pero el estado del workspace prohíbe la acción (ej. publicar un artifact que sigue en draft). |
404 | not_found | El recurso no existe en el workspace asociado a este token. |
Cada response incluye el header X-Request-Id. Correlacioná contra los logs del operador por ese id; request_id no aparece en el body del error. Ver Errores para la taxonomía completa.
Firmas de webhook (esquema distinto)
Si estás consumiendo eventos desde Whet (en lugar de llamar al API de Whet), el esquema es distinto: los webhooks llegan firmados con HMAC usando el WEBHOOK_SIGNING_SECRET compartido al provisionar. Ver Webhooks · verificación HMAC para el algoritmo.
Multi-tenant / Whet Cloud (diferido)
El modelo de deployment actual es single-tenant: una instancia Whet por cliente, un workspace, un agent token. Whet Cloud (multi-tenant) va a introducir emisión de tokens por org vía better-auth — AGENT_API_TOKEN se va a convertir en fallback solo para deployments self-hosted. Sin timeline aún; trackeable por el roadmap.