> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticacion

> Como iniciar sesion con Better Auth, usar el bearer token y manejar errores de acceso

## 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](/authorization-and-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](/platform-guide) y [Permisos y roles](/authorization-and-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.

```bash theme={null}
curl -i -X POST "https://api.raul.ugps.io/api/better-auth/sign-in/email" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@ugps.cl",
    "password": "password123"
  }'
```

Respuesta esperada (fragmento de headers):

```
set-auth-token: <token-de-sesion>
```

```json theme={null}
{
  "user": {
    "id": "uuid",
    "email": "admin@ugps.cl"
  }
}
```

## Header de autorizacion

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

```bash theme={null}
curl "https://api.raul.ugps.io/api/auth/users/me" \
  -H "Authorization: Bearer TU_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

| HTTP | Causa habitual | Que hacer |
| - | - | - |
| `400` | Payload invalido | Revisar campos requeridos |
| `401` | Token ausente, invalido, expirado, o un JWT legacy de antes de la migracion | Volver a hacer sign-in |
| `403` | Usuario sin permisos o deshabilitado | Revisar rol y estado de cuenta |

## 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](/ai-consumption#servidor-mcp).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.