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

# API de autenticacion

> Autenticacion de usuarios, registro y gestion de sesiones

## Resumen

La API de autenticacion gestiona registro de usuarios, login, sesiones, verificacion de email y restablecimiento de contrasena. Toda la autenticacion usa cookies HTTP-only seguras para sesiones con tokens JWT.

## Flujo de autenticacion

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client
    participant API
    participant Email

    User->>Client: Enter credentials
    Client->>API: POST /auth/register
    API->>Email: Send verification email
    API-->>Client: Success (unverified account)
    User->>Email: Click verification link
    Email->>API: POST /auth/verify-email
    API-->>Client: Email verified
    User->>Client: Login
    Client->>API: POST /auth/login
    API-->>Client: Set HTTP-only cookie
    Client->>API: Authenticated requests
```

## Endpoints

### Registrar nuevo usuario

<ParamField path="POST" type="endpoint">
  /auth/register
</ParamField>

Crea una cuenta de usuario nueva. Se envia un enlace de verificacion al email indicado.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com",
  "name": "John Doe",
  "password": "SecurePassword123!"
}
```

<ParamField body="email" type="string" required>
  Email valido
</ParamField>

<ParamField body="name" type="string" required>
  Nombre completo (minimo 2 caracteres)
</ParamField>

<ParamField body="password" type="string" required>
  Contrasena segura (minimo 8 caracteres)
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Registration successful. Please check your email to verify your account.",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "emailVerified": false,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}
```

<Warning>
  Los usuarios deben verificar su email antes de acceder por completo a la plataforma.
</Warning>

***

### Login

<ParamField path="POST" type="endpoint">
  /auth/login
</ParamField>

Autentica al usuario y crea una sesion.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}
```

<ParamField body="email" type="string" required>
  Email del usuario
</ParamField>

<ParamField body="password" type="string" required>
  Contrasena del usuario
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true
  }
}
```

**Cookies establecidos:**

* `accessToken` - HTTP-only, Secure, SameSite=Strict (15 minutos)
* `refreshToken` - HTTP-only, Secure, SameSite=Strict (7 dias)

***

### Obtener usuario actual

<ParamField path="GET" type="endpoint">
  /auth/me
</ParamField>

Devuelve la informacion del usuario autenticado.

**Headers:**

```
Cookie: accessToken=...
```

**Response:**

```json theme={null}
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}
```

***

### Renovar access token

<ParamField path="POST" type="endpoint">
  /auth/refresh
</ParamField>

Obtiene un nuevo access token usando el refresh token.

**Headers:**

```
Cookie: refreshToken=...
```

**Response:**

```json theme={null}
{
  "ok": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER"
  }
}
```

**Cookies actualizados:**

* Nuevo `accessToken`
* `refreshToken` rotado por seguridad

***

### Logout

<ParamField path="POST" type="endpoint">
  /auth/logout
</ParamField>

Cierra sesion e invalida tokens.

**Headers:**

```
Cookie: accessToken=...
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Logged out successfully"
}
```

**Cookies eliminados:**

* `accessToken` removido
* `refreshToken` removido

***

### Verificar email

<ParamField path="POST" type="endpoint">
  /auth/verify-email
</ParamField>

Verifica el email del usuario usando el token enviado por email.

**Request Body:**

```json theme={null}
{
  "token": "verification_token_from_email"
}
```

<ParamField body="token" type="string" required>
  Token de verificacion de email
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Email verified successfully. You can now log in."
}
```

***

### Reenviar verificacion de email

<ParamField path="POST" type="endpoint">
  /auth/send-email-verification
</ParamField>

Solicita un nuevo email de verificacion si el anterior expiro o se perdio.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com"
}
```

<ParamField body="email" type="string" required>
  Email del usuario
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Verification email sent. Please check your inbox."
}
```

**Rate Limit:**

Este endpoint tiene limite para evitar abuso:

* **5 requests por hora** por email

***

### Olvide mi contrasena

<ParamField path="POST" type="endpoint">
  /auth/forgot-password
</ParamField>

Solicita un enlace de restablecimiento via email.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com"
}
```

<ParamField body="email" type="string" required>
  Email del usuario
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent."
}
```

<Info>
  Por seguridad, la API siempre responde exito aunque el email no exista.
</Info>

***

### Restablecer contrasena

<ParamField path="POST" type="endpoint">
  /auth/reset-password
</ParamField>

Restablece la contrasena usando el token del email.

**Request Body:**

```json theme={null}
{
  "token": "reset_token_from_email",
  "password": "NewSecurePassword123!"
}
```

<ParamField body="token" type="string" required>
  Token de restablecimiento
</ParamField>

<ParamField body="password" type="string" required>
  Nueva contrasena (minimo 8 caracteres)
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Password reset successful. You can now log in with your new password."
}
```

***

## Funciones de seguridad

### Cookies HTTP-only

Los tokens de sesion se guardan en cookies HTTP-only para prevenir ataques XSS. JavaScript no puede acceder a estas cookies.

### Flag Secure

Las cookies usan `Secure`, por lo que solo se transmiten por HTTPS en produccion.

### Politica SameSite

Las cookies usan `SameSite=Strict` para prevenir ataques CSRF.

### Rotacion de tokens

Los refresh tokens rotan en cada uso para minimizar riesgos si un token se compromete.

### Requisitos de contrasena

* Minimo 8 caracteres
* Recomendado: mezcla de mayusculas, minusculas, numeros y caracteres especiales

### Expiracion de tokens

* **Access Token:** 15 minutos
* **Refresh Token:** 7 dias
* **Verification Token:** 24 horas
* **Reset Token:** 1 hora

## Codigos de error

| Code                   | Status | Descripcion                        |
| ---------------------- | ------ | ---------------------------------- |
| `INVALID_CREDENTIALS`  | 401    | Email o contrasena incorrectos     |
| `EMAIL_ALREADY_EXISTS` | 409    | Email ya registrado                |
| `EMAIL_NOT_VERIFIED`   | 403    | Se requiere verificacion de email  |
| `INVALID_TOKEN`        | 400    | Token invalido o expirado          |
| `TOKEN_EXPIRED`        | 401    | Token expirado                     |
| `WEAK_PASSWORD`        | 400    | La contrasena no cumple requisitos |
| `RATE_LIMIT_EXCEEDED`  | 429    | Demasiadas solicitudes             |

## Casos de uso

### Ejemplo 1: Flujo completo de registro

```bash theme={null}
# Step 1: Register
curl -X POST "https://api.steerai.autos/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com",
    "name": "Auto Dealer",
    "password": "SecurePass123!"
  }'

# Step 2: User receives email and verifies
curl -X POST "https://api.steerai.autos/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "verification_token_from_email"
  }'

# Step 3: Login
curl -X POST "https://api.steerai.autos/v1/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "dealer@example.com",
    "password": "SecurePass123!"
  }'
```

### Ejemplo 2: Flujo de restablecimiento de contrasena

```bash theme={null}
# Step 1: Request reset
curl -X POST "https://api.steerai.autos/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com"
  }'

# Step 2: Reset with token from email
curl -X POST "https://api.steerai.autos/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "password": "NewSecurePass123!"
  }'
```

### Ejemplo 3: Refresh de token

```bash theme={null}
# Refresh access token before it expires
curl -X POST "https://api.steerai.autos/v1/auth/refresh" \
  -b cookies.txt \
  -c cookies.txt
```

## Implementacion de cliente

### JavaScript/Node.js

```javascript theme={null}
class AuthClient {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  async register(email, name, password) {
    const response = await fetch(`${this.baseURL}/auth/register`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, name, password })
    });
    return response.json();
  }

  async login(email, password) {
    const response = await fetch(`${this.baseURL}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include', // Important for cookies
      body: JSON.stringify({ email, password })
    });
    return response.json();
  }

  async getCurrentUser() {
    const response = await fetch(`${this.baseURL}/auth/me`, {
      credentials: 'include'
    });
    return response.json();
  }

  async logout() {
    const response = await fetch(`${this.baseURL}/auth/logout`, {
      method: 'POST',
      credentials: 'include'
    });
    return response.json();
  }
}
```

## Mejores practicas

<AccordionGroup>
  <Accordion title="Usa siempre HTTPS en produccion">
    Nunca transmitas credenciales por HTTP sin cifrado.
  </Accordion>

  <Accordion title="Implementa refresh de token en el cliente">
    Renueva tokens antes de que expiren para mantener la sesion.
  </Accordion>

  <Accordion title="Guarda refresh tokens de forma segura">
    Usa cookies HTTP-only (manejadas por la API) en lugar de localStorage.
  </Accordion>

  <Accordion title="Exige politicas fuertes de contrasenas">
    Requiere contrasenas con complejidad y longitud adecuadas.
  </Accordion>

  <Accordion title="Implementa rate limiting">
    Protege endpoints de autenticacion de ataques brute-force.
  </Accordion>

  <Accordion title="Registra eventos de autenticacion">
    Monitorea logins, resets de contrasena y actividad sospechosa.
  </Accordion>
</AccordionGroup>

## Recursos relacionados

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/es/getting-started/authentication">
    Guia rapida de autenticacion
  </Card>

  <Card title="Guia de seguridad" icon="shield" href="/es/guides/security">
    Mejores practicas de seguridad
  </Card>

  <Card title="API de usuarios" icon="user" href="/es/api-reference/users/management">
    Endpoints de gestion de usuarios y perfil
  </Card>

  <Card title="API de equipos" icon="users" href="/es/api-reference/teams/overview">
    Colaboracion de equipos y permisos
  </Card>
</CardGroup>