Authentication API

Sistema de autenticación basado en AWS Cognito con tokens JWT. Gestión completa de usuarios, registro, login, y verificación.

---

Visión General

Base Path: /api/auth

Autenticación: La mayoría de endpoints requieren token JWT válido

User Types (Prisma enum):

• COMPANY - Investigador/Empresa (solicita financiación)
• INVESTOR - Financiador/Inversor (ofrece capital)
• CONSULTANT - Consultor BIK (gestiona empresas)
• ADMIN - Administrador plataforma

---

Endpoints

POST /api/auth/register

Registra un nuevo usuario en la plataforma.

Autenticación: No requerida

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "userType": "COMPANY",
  "companyName": "Tech Innovations SL",
  "nif": "B12345678"
}

Validación:

• Email válido y único
• Password mínimo 8 caracteres, mayúscula, minúscula, número, símbolo
• userType debe ser: COMPANY, INVESTOR, CONSULTANT
• NIF válido español (formato B12345678)

Response 201:

{
  "success": true,
  "data": {
    "userId": "usr_abc123",
    "email": "user@example.com",
    "userType": "COMPANY",
    "cognitoId": "cognito_xyz789",
    "verified": false
  }
}

Errors:

• 400 - Email ya existe, validación fallida
• 500 - Error del servidor

---

POST /api/auth/login

Autentica usuario y retorna tokens JWT.

Autenticación: No requerida

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response 200:

{
  "success": true,
  "data": {
    "idToken": "eyJraWQiOiJ...",
    "accessToken": "eyJraWQiOiJ...",
    "refreshToken": "eyJjdHkiOiJ...",
    "expiresIn": 3600,
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "userType": "COMPANY",
      "verified": true
    }
  }
}

Tokens:

• idToken: Usar en header Authorization para API requests
• accessToken: Token de acceso Cognito
• refreshToken: Para renovar tokens expirados
• expiresIn: Segundos hasta expiración (3600 = 1 hora)

Errors:

• 401 - Credenciales inválidas
• 403 - Usuario no verificado
• 500 - Error del servidor

---

GET /api/auth/me

Obtiene información del usuario autenticado actual.

Autenticación: Requerida (JWT)

Headers:

Authorization: Bearer <idToken>

Response 200:

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "userType": "COMPANY",
    "verified": true,
    "createdAt": "2025-01-01T00:00:00Z",
    "profile": {
      "companyName": "Tech Innovations SL",
      "nif": "B12345678",
      "phone": "+34600000000",
      "address": "Calle Mayor 1, Bilbao"
    },
    "companies": [
      {
        "id": "comp_123",
        "name": "Tech Innovations SL",
        "nif": "B12345678"
      }
    ]
  }
}

Errors:

• 401 - Token inválido o ausente
• 404 - Usuario no encontrado

---

GET /api/auth/health

Verifica el estado del servicio de autenticación.

Autenticación: No requerida

Response 200:

{
  "success": true,
  "data": {
    "status": "healthy",
    "cognito": "connected",
    "database": "connected",
    "timestamp": "2025-01-03T10:30:00Z"
  }
}

Errors:

• 503 - Servicio no disponible

---

POST /api/auth/refresh

Renueva tokens JWT usando refreshToken.

Autenticación: Requerida (refreshToken)

Request Body:

{
  "refreshToken": "eyJjdHkiOiJ..."
}

Response 200:

{
  "success": true,
  "data": {
    "idToken": "eyJraWQiOiJ...",
    "accessToken": "eyJraWQiOiJ...",
    "expiresIn": 3600
  }
}

Errors:

• 401 - Refresh token inválido o expirado
• 500 - Error del servidor

---

POST /api/auth/forgot-password

Inicia proceso de recuperación de contraseña.

Autenticación: No requerida

Request Body:

{
  "email": "user@example.com"
}

Response 200:

{
  "success": true,
  "data": {
    "message": "Código de verificación enviado a user@example.com"
  }
}

Nota: Por seguridad, siempre retorna 200 incluso si el email no existe.

---

POST /api/auth/reset-password

Completa el proceso de recuperación de contraseña.

Autenticación: No requerida

Request Body:

{
  "email": "user@example.com",
  "code": "123456",
  "newPassword": "NewSecurePassword123!"
}

Response 200:

{
  "success": true,
  "data": {
    "message": "Contraseña actualizada correctamente"
  }
}

Errors:

• 400 - Código inválido o expirado
• 500 - Error del servidor

---

POST /api/auth/change-password

Cambia la contraseña del usuario autenticado.

Autenticación: Requerida (JWT)

Request Body:

{
  "oldPassword": "OldPassword123!",
  "newPassword": "NewSecurePassword123!"
}

Response 200:

{
  "success": true,
  "data": {
    "message": "Contraseña actualizada correctamente"
  }
}

Errors:

• 401 - Contraseña antigua incorrecta
• 400 - Nueva contraseña no cumple requisitos

---

POST /api/auth/verify-email

Verifica el email del usuario con código de verificación.

Autenticación: No requerida

Request Body:

{
  "email": "user@example.com",
  "code": "123456"
}

Response 200:

{
  "success": true,
  "data": {
    "verified": true,
    "message": "Email verificado correctamente"
  }
}

Errors:

• 400 - Código inválido o expirado
• 404 - Usuario no encontrado

---

POST /api/auth/resend-verification

Reenvía código de verificación de email.

Autenticación: No requerida

Request Body:

{
  "email": "user@example.com"
}

Response 200:

{
  "success": true,
  "data": {
    "message": "Código de verificación enviado"
  }
}

---

POST /api/auth/admin/sync-user

ADMIN ONLY: Sincroniza usuario de Cognito con base de datos.

Autenticación: Requerida (JWT de ADMIN)

Request Body:

{
  "cognitoId": "cognito_xyz789",
  "email": "user@example.com"
}

Response 200:

{
  "success": true,
  "data": {
    "userId": "usr_abc123",
    "synced": true
  }
}

Errors:

• 403 - No eres administrador
• 404 - Usuario de Cognito no encontrado

---

Flujos Completos

Flujo de Registro

sequenceDiagram
    Client->>API: POST /api/auth/register
    API->>Cognito: CreateUser
    Cognito->>Client: Código verificación (email)
    Client->>API: POST /api/auth/verify-email
    API->>Cognito: ConfirmSignUp
    Cognito->>API: Usuario verificado
    API->>Client: verified: true

Pasos:

1. Cliente llama POST /api/auth/register
2. Sistema crea usuario en Cognito
3. Cognito envía código de verificación al email
4. Cliente llama POST /api/auth/verify-email con código
5. Usuario verificado, puede hacer login

---

Flujo de Login

sequenceDiagram
    Client->>API: POST /api/auth/login
    API->>Cognito: InitiateAuth
    Cognito->>API: Tokens JWT
    API->>Client: idToken, accessToken, refreshToken
    Client->>API: GET /api/auth/me (with idToken)
    API->>Client: User data

Pasos:

1. Cliente llama POST /api/auth/login
2. Sistema autentica con Cognito
3. Cognito retorna tokens JWT
4. Cliente guarda idToken para futuras peticiones
5. Cliente puede llamar GET /api/auth/me para obtener datos de usuario

---

Flujo de Recuperación de Contraseña

sequenceDiagram
    Client->>API: POST /api/auth/forgot-password
    API->>Cognito: ForgotPassword
    Cognito->>Client: Código verificación (email)
    Client->>API: POST /api/auth/reset-password
    API->>Cognito: ConfirmForgotPassword
    Cognito->>API: Contraseña actualizada
    API->>Client: success: true

Pasos:

1. Cliente llama POST /api/auth/forgot-password
2. Cognito envía código al email
3. Cliente llama POST /api/auth/reset-password con código y nueva contraseña
4. Contraseña actualizada, puede hacer login con nueva contraseña

---

Verificación de Token (Backend)

Para verificar tokens JWT en endpoints protegidos:

import { verifyCognitoToken } from '@/lib/auth/verify-cognito-token';

export async function GET(request: Request) {
  // Verificar token
  const authResult = await verifyCognitoToken(request);

  if (!authResult.valid) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  // Token válido, obtener datos de usuario
  const { userId, email, userType } = authResult.user;

  // Tu lógica aquí...
}

---

Frontend (React Hooks)

useCognitoFetch

Hook para peticiones autenticadas:

import { useCognitoFetch } from '@/hooks/useCognitoFetch';

function MyComponent() {
  const { cognitoFetch } = useCognitoFetch();

  const loadUserData = async () => {
    const response = await cognitoFetch('/api/auth/me', {
      method: 'GET'
    });

    const data = await response.json();
    console.log(data);
  };

  return <button onClick={loadUserData}>Load Profile</button>;
}

useCognitoUser

Hook para obtener usuario actual:

import { useCognitoUser } from '@/hooks/useCognitoUser';

function MyComponent() {
  const { user, loading, error } = useCognitoUser();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return <div>Welcome, {user.email}!</div>;
}

---

Seguridad

Requisitos de Contraseña

• Mínimo 8 caracteres
• Al menos 1 mayúscula
• Al menos 1 minúscula
• Al menos 1 número
• Al menos 1 símbolo especial (!@#$%^&*)

Tokens JWT

Estructura:

{
  "header": {
    "alg": "RS256",
    "kid": "abcd1234"
  },
  "payload": {
    "sub": "cognito_xyz789",
    "email": "user@example.com",
    "cognito:groups": ["COMPANY"],
    "exp": 1640000000,
    "iat": 1639996400
  }
}

Expiración:

• idToken: 1 hora
• accessToken: 1 hora
• refreshToken: 30 días

Rate Limiting

• Login: 5 intentos/minuto
• Registro: 3 intentos/minuto
• Reset password: 3 intentos/5 minutos

---

Errores Comunes

401 Unauthorized

Causa: Token inválido, expirado, o ausente

Solución: Renovar token con POST /api/auth/refresh o hacer login nuevamente

403 Forbidden

Causa: Usuario no tiene permisos para el recurso

Solución: Verificar que el userType del usuario tiene acceso al endpoint

400 Bad Request - "Email already exists"

Causa: Email ya registrado en el sistema

Solución: Usar otro email o recuperar contraseña si olvidaste la cuenta

400 Bad Request - "Password does not meet requirements"

Causa: Contraseña no cumple requisitos de seguridad

Solución: Usar contraseña con 8+ caracteres, mayúscula, minúscula, número, símbolo

---

Próximos Pasos

• Proyectos API - Crear y gestionar proyectos
• Marketplace API - Buscar y filtrar proyectos
• Ofertas API - Sistema de ofertas

---

Última actualización: 3 enero 2026 | Tiempo de lectura: 12 minutos