Skip to main content

​
Resumen

Los endpoints protegidos de Raul API usan autenticacion Bearer. Better Auth es el unico mecanismo de sesion de backoffice: el login emite una sesion opaca de 30 dias deslizante (sin renovacion manual). El flujo legacy con JWT firmado (/api/auth/login, /refresh, /logout, /session/upgrade) ya no existe. Para permisos y diferencias entre backoffice vs portal, revisa tambien Permisos y roles. Flujo recomendado:
  1. POST /api/better-auth/sign-in/email
  2. Guardar el token del header de respuesta set-auth-token
  3. Enviar Authorization: Bearer <token> en cada request
  4. La sesion se renueva sola mientras haya actividad (deslizante, sin endpoint de refresh)
  5. Invalidar sesion con POST /api/better-auth/sign-out cuando corresponda

​
Base URL

  • https://api.raul.ugps.io

​
Dos superficies de acceso

  • Backoffice/API interna: Better Auth (sesion opaca), unico mecanismo de sesion.
  • Portal cliente: magic link + token propio del portal (JWT_SECRET).
En esta pagina se documenta el acceso del backoffice. El portal vive en Plataforma y backoffice y Permisos y roles.

​
Login

Usa POST /api/better-auth/sign-in/email para obtener una sesion. El token de sesion viaja en el header de respuesta set-auth-token (plugin bearer de Better Auth), no en el body.
Respuesta esperada (fragmento de headers):

​
Header de autorizacion

Para cualquier endpoint protegido, usa el token capturado de set-auth-token:

​
Validar sesion

Usa GET /api/auth/users/me para confirmar que el token sigue vigente y conocer la identidad activa. Esto sirve para:
  • validar que el login fue correcto
  • inspeccionar permisos efectivos
  • comprobar si el token sigue usable antes de ejecutar flujos largos

​
Cerrar sesion

Usa POST /api/better-auth/sign-out para invalidar la sesion actual. Eso aplica cuando:
  • el usuario cierra sesion manualmente
  • quieres revocar sesiones previas
  • detectas credenciales comprometidas

​
Errores comunes

​
Buenas practicas

  • No persistir tokens de sesion en logs.
  • Capturar el token desde el header set-auth-token, no asumas que viene en el body.
  • Validar sesion con /users/me al inicio de integraciones largas.

​
Endpoints relacionados

  • POST /api/better-auth/sign-in/email
  • POST /api/better-auth/sign-out
  • GET /api/auth/users/me
  • POST /api/auth/password-reset/request
  • POST /api/auth/password-reset/confirm

​
Agentes y servidor MCP

Los agentes de IA pueden usar el servidor MCP en https://mcp-raul.ugps.io/mcp, que autentica a cada persona con su propia cuenta de Raul mediante OAuth 2.1 sobre este mismo login de Better Auth. El token que recibe el agente es un JWT de Better Auth con scope raul:api, vida de 1 hora y refresh de 30 días; la API acepta ese mismo JWT en SessionAuthGuard. Ver Para IA.