Autenticación y permisos

Obtener un token Bearer

Las integraciones se autentican con un usuario dedicado. AGOS no ofrece en este contrato una API key de servicio ni un flujo OAuth de client credentials para acceder a su API REST.

POST /api/auth/login
Content-Type: application/json

{
  "email": "integracion@example.com",
  "password": "<contraseña-del-almacén-de-secretos>",
  "useCookie": false
}

Respuesta 200:

{ "token": "<jwt>", "plan": "Standard" }

En las peticiones siguientes, envía Authorization: Bearer <jwt>. No transmitas el token en la URL ni lo registres en logs.

Expiración y revocación

El JWT usa HS256 y vence por defecto a las 8 horas; el operador puede cambiar ese plazo. No hay un endpoint de refresh documentado: para obtener otro token, vuelve a iniciar sesión.

• Mantén el token en memoria o en un almacenamiento protegido del backend y reutilízalo hasta su renovación.
• Ante un 401, permite como máximo una reautenticación controlada. Si vuelve a fallar, detén el flujo y solicita revisión.
• El bloqueo del usuario, un cambio de contraseña o de roles pueden invalidar los tokens inmediatamente.
• Si cambian los permisos de un rol, inicia una nueva sesión para recibir los permisos actualizados.
• POST /api/auth/logout borra la cookie del panel; no revoca un JWT Bearer existente.

No supongas que un token está autorizado por el solo hecho de decodificarlo en tu aplicación: el servidor decide si sigue siendo válido.

Asignar el mínimo privilegio

Un administrador debe crear un rol específico para la integración. La cuota de chat es por usuario, por lo que varias aplicaciones compartiendo una cuenta también comparten su consumo.

Operación	Permisos necesarios
Conversar en /api/chat	Sesión válida; no exige un permiso específico
Listar agentes	agents.read
Cargar documentos	knowledge.write
Consultar indexación	knowledge.read
Sincronizar un conector	connectors.read y connectors.write
Crear una licencia de widget	planlimits.read y planlimits.write

Los permisos de clase y de operación se acumulan. Un token válido sin todos los permisos responde 403; volver a iniciar sesión no concede permisos nuevos.

Consulta el catálogo completo de permisos.

Sesión del panel y protección CSRF

Con useCookie: true, AGOS devuelve el perfil de sesión y guarda el JWT en la cookie agos_session, HttpOnly y SameSite=Strict. Las operaciones POST, PUT y DELETE con cookie requieren X-Agos-Csrf: 1.

Si una petición lleva Authorization, el servidor ignora la cookie. Para integrar sistemas, utiliza Bearer; no automatices la sesión del navegador.

Autorización del widget

Las operaciones públicas del widget no usan JWT. Reciben el licenseId del usuario final y están sujetas a vigencia y cupo. La lectura de apariencia es pública, pero conversar requiere una licencia de uso válida.

Un licenseId permite consumo: trátalo como una credencial de uso. No publiques una licencia compartida de producción en HTML estático ni en documentación. Consulta Widgets e integración web.

Red y protección de secretos

La API no habilita CORS. Para una web en otro dominio, usa tu propio backend o un proxy de mismo origen con autorización por usuario. No desactives controles de seguridad para evitar esta restricción.

Los secretos deben permanecer en un gestor de credenciales. Exige HTTPS en producción y evita registrar cuerpos de login, encabezados Bearer o licencias de uso.

El login admite 10 peticiones por minuto por IP. No inicies sesión antes de cada mensaje y evita reintentos en bucle.