Autenticación

La API utiliza JSON Web Tokens (JWT) para autenticación.

Conceptos Básicos

¿Qué es JWT?

JWT (JSON Web Token) es un estándar abierto que define una forma compacta y autónoma de transmitir información de forma segura entre partes como un objeto JSON.

sequenceDiagram
  participant C as Cliente
  participant A as API Auth
  participant R as API Recursos

  C->>A: POST /api/auth/login (credenciales)
  A->>C: Token JWT + cookie HttpOnly
  C->>R: GET /api/resources (Authorization: Bearer token)
  R->>C: Datos protegidos

Estructura del Token

Un JWT consta de tres partes separadas por puntos:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9  ← Header
.
eyJ1c2VySWQiOiIxMjM0NTYiLCJlbWFpbCI6InVzZXJAZXhhbXBsZS5jb20ifQ  ← Payload
.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c  ← Signature

Obtener Token

Login

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

Request Body:

{
  "email": "usuario@brysa.cl",
  "password": "su-contraseña"
}

Response (200 OK):

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 123,
      "email": "usuario@brysa.cl",
      "fullName": "Juan Pérez",
      "role": "cecom",
      "tenantId": 1,
      "contractId": 10,
      "allowedModules": ["dashboard", "emergency-log"]
    }
  }
}

Response (401 Unauthorized):

{
  "status": "error",
  "message": "Credenciales inválidas"
}

Usar el Token

Header Authorization

Incluya el token en todas las requests autenticadas:

GET /api/brigadista
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Importante

• El token debe ir precedido por la palabra Bearer y un espacio
• El token es sensible a mayúsculas
• No incluya comillas alrededor del token

Expiración

Tiempos de Vida

Tipo	Duración
Access Token	24 horas

No existe endpoint productivo de refresh token en la versión actual.

Detectar Expiración

Cuando el token expira, la API retorna:

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "message": "Token expirado"
}

Cerrar Sesión

La API actual no expone POST /api/auth/logout. El cierre de sesión de la SPA limpia el estado local/cookies de navegación desde el cliente.

Seguridad

Recomendaciones

• No almacenar tokens en localStorage (vulnerable a XSS)
• Preferir httpOnly cookies cuando sea posible
• Reautenticar cuando el token expire
• No compartir tokens entre aplicaciones

Información en el Token

El payload del token incluye:

Campo	Descripción
userId	ID del usuario
email	Email del usuario
role	Rol del usuario
tenantId	ID del tenant
iat	Fecha de emisión
exp	Fecha de expiración

Nunca

• Almacene contraseñas en el cliente
• Transmita tokens por URL (query string)
• Use tokens en conexiones HTTP (solo HTTPS)

Errores de Autenticación

Código	Mensaje	Causa
401	Token no proporcionado	Falta header Authorization
401	Token inválido	Token malformado o manipulado
401	Token expirado	El token ya no es válido
403	Sin permisos	Usuario autenticado pero sin acceso

Código de Ejemplo

JavaScript (Fetch)

// Login
const response = await fetch('https://api.cecom-brysa.cl/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'usuario@brysa.cl',
    password: 'contraseña'
  })
});

const { data } = await response.json();
const token = data.token;

// Usar token en requests
const recursos = await fetch('https://api.cecom-brysa.cl/api/resource-panel/resources', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

cURL

# Login
curl -X POST https://api.cecom-brysa.cl/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"usuario@brysa.cl","password":"contraseña"}'

# Usar token
curl https://api.cecom-brysa.cl/api/brigadista \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

---

Siguiente paso

Revise la sección de Errores para entender cómo manejar respuestas de error.