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

Identity Auth API

Endpoints activos

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

Endpoints que no forman parte del diseño vigente

No documentar ni crear como ruta válida:

GET /identity/companies
GET /account/companies

Motivo:

• identity no debe devolver fichas completas de empresa.
• companies ya depende de identity para autenticación.
• Un endpoint de ese tipo introduciría el ciclo identity -> companies -> identity.

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 companies accesibles
• 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
• no debe llevar X-Company-Id

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

• no debe llevar X-Company-Id
• para logout normal, enviar el refresh_token actual
• 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;
};

Notas

• no debe llevar X-Company-Id

GET /companies/available

Headers

Authorization: Bearer <access_token>

Response

export type AvailableCompaniesResponseDTO = {
  companies: AvailableCompanyDTO[];
};

export type AvailableCompanyDTO = {
  id: string;
  legal_name: string;
  trade_name: string | null;
  tin: string | null;
  slug: string;
  email: string | null;
  phone: string | null;
  website: string | null;
  status: "active";
};

Notas

• usa autenticación, no tenant context
• no requiere X-Company-Id
• usa requireIdentityAuthenticated(params)
• devuelve solo companies activas accesibles para la cuenta autenticada
• no modifica sesión ni access token

Errores esperados

400 -> request inválida o UUID de X-Company-Id mal formado
401 -> access token ausente/inválido/expirado o credenciales inválidas
403 -> contexto tenant inválido, company no accesible o company no activa
500 -> error inesperado