Uecko_ERP/docs/architecture/identity-auth-api.md

Identity Auth API

Endpoints disponibles

POST /identity/auth/login
POST /identity/auth/refresh
POST /identity/auth/logout
GET  /identity/auth/session

POST /identity/auth/login

Request

export type LoginWithPasswordRequestDTO = {
  email: string;
  password: string;
};

Response

export type LoginWithPasswordResponseDTO = {
  access_token: string;
  refresh_token: string;
  account: AuthenticatedAccountDTO;
};

export type AuthenticatedAccountDTO = {
  id: string;
  email: string;
  name: string;
  avatar_url: string | null;
  language_code: string;
};

Notas

• No requiere Authorization.
• No requiere X-Company-Id.
• No devuelve empresas accesibles todavía.
• No devuelve roles ni permisos.
• El access token no contiene companyId.

POST /identity/auth/refresh

Request

export type RefreshSessionRequestDTO = {
  refresh_token: string;
};

Response

export type RefreshSessionResponseDTO = {
  access_token: string;
  refresh_token: string;
};

Notas

• El refresh token se rota.
• El cliente debe reemplazar ambos tokens por los nuevos.
• El refresh token anterior no debe reutilizarse tras una renovación correcta.

POST /identity/auth/logout

Headers

Authorization: Bearer <access_token>

Request

export type LogoutRequestDTO = {
  refresh_token?: string;
  all_sessions?: boolean;
};

Response

export type LogoutResponseDTO = {
  success: true;
};

Reglas

• Para logout normal, enviar el refresh_token actual.
• Para cerrar todas las sesiones, enviar all_sessions: true.
• Si logout falla por expiración de token, el frontend debe limpiar sesión igualmente.

GET /identity/auth/session

Headers

Authorization: Bearer <access_token>

Response

export type CurrentSessionResponseDTO = {
  account: AuthenticatedAccountDTO;
};

Errores esperados

400 -> request inválida o header mal formado
401 -> access token ausente/inválido/expirado o credenciales inválidas
403 -> contexto de empresa requerido en rutas tenant-scoped
500 -> error inesperado

Rutas tenant-scoped

Las rutas de negocio tenant-scoped deben enviar:

Authorization: Bearer <access_token>
X-Company-Id: <uuid-company>

Actualmente X-Company-Id se valida sintácticamente como UUID y se publica como req.user.companyId.

La validación real de membership queda pendiente.