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

# Identity Auth API

## Endpoints activos

```http
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:

```http
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

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

### Response

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

```ts
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

```ts
export type RefreshSessionRequestDTO = {
  refresh_token: string;
};
```

### Response

```ts
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

```http
Authorization: Bearer <access_token>
```

### Request

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

### Response

```ts
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

```http
Authorization: Bearer <access_token>
```

### Response

```ts
export type CurrentSessionResponseDTO = {
  account: AuthenticatedAccountDTO;
};
```

### Notas

- no debe llevar `X-Company-Id`

## GET `/companies/available`

### Headers

```http
Authorization: Bearer <access_token>
```

### Response

```ts
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

```txt
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
```