Verificar Email

Verifica la dirección de email de un usuario usando el token de verificación enviado por email, y devuelve tokens de autenticación.

Endpoint

POST /api/v1/auth/verify-email

Autenticación

No se requiere autenticación (endpoint público).

Request

Content-Type

application/json

Request Body

Campo	Tipo	Requerido	Descripción
code	string	Sí	Token de verificación del enlace del email

Ejemplo de Request

{
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response

Response Exitoso (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Campos del Response

Campo	Tipo	Descripción
access_token	string	Token de acceso JWT para requests de API (expira en 30 minutos)
refresh_token	string	Token refresh JWT para obtener nuevos tokens de acceso (expira en 7 días)
token_type	string	Siempre "bearer"

Expiración de Tokens

Tipo de Token	Expiración	Propósito
Access Token	30 minutos	Hacer requests de API
Refresh Token	7 días	Obtener nuevos tokens de acceso

Cuando el token de acceso expire, usa el endpoint de refresh para obtener uno nuevo.

Ejemplos

curl -X POST https://api.callcov.com/api/v1/auth/verify-email \
-H "Content-Type: application/json" \
-d '{
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Integración con Frontend

Flujo típico en una aplicación web:

// 1. Usuario hace clic en enlace de verificación: https://app.callcov.com/verify-email?token=abc123...
// 2. Frontend extrae token del parámetro de URL query
const urlParams = new URLSearchParams(window.location.search);
const verificationToken = urlParams.get('token');

// 3. Llamar endpoint verify-email
const response = await fetch('https://api.callcov.com/api/v1/auth/verify-email', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: verificationToken })
});

if (response.ok) {
  const { access_token, refresh_token } = await response.json();

  // 4. Almacenar tokens
  localStorage.setItem('access_token', access_token);
  localStorage.setItem('refresh_token', refresh_token);

  // 5. Redirigir al dashboard
  window.location.href = '/dashboard';
} else {
  // Mostrar mensaje de error
  alert('La verificación falló. El enlace puede haber expirado.');
}

Errores

400 Bad Request

Token de verificación inválido:

{
  "detail": "Token de verificación inválido"
}

El token de verificación ha expirado:

{
  "detail": "El token de verificación ha expirado"
}

404 Not Found

Usuario no encontrado (el token era válido pero el usuario fue eliminado):

{
  "detail": "Usuario no encontrado"
}

Uso de Tokens

Después de la verificación, usa el token de acceso para requests de API autenticados:

# Usando el token de acceso
curl https://api.callcov.com/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Consideraciones de Seguridad

• Tokens de un solo uso: Cada token de verificación solo puede usarse una vez
• Tiempo limitado: Los tokens expiran en 15 minutos (configurable)
• Almacenamiento seguro: Almacenar tokens de forma segura (usar cookies httpOnly para apps web)
• Solo HTTPS: Siempre usar HTTPS en producción

Mejores Prácticas de Almacenamiento de Tokens

Aplicaciones Web

// ✅ BUENO: Usar cookies httpOnly (configuradas por backend)
// Access token en cookie httpOnly (protegido de XSS)
// Refresh token en cookie httpOnly (protegido de XSS)

// ❌ MALO: localStorage (vulnerable a XSS)
localStorage.setItem('access_token', token);

Aplicaciones Móviles

// ✅ BUENO: Usar almacenamiento seguro
// iOS: Keychain
// Android: Keystore o EncryptedSharedPreferences

Vida Útil del Token de Verificación

Evento	Vida Útil
Token creado	15 minutos
Token usado	Inmediatamente invalidado
Token expirado	Automáticamente invalidado

Si el token expira, los usuarios pueden solicitar uno nuevo vía reenviar verificación.

Flujo Completo de Registro

1. Usuario envía formulario de registro
2. Backend crea usuario (sin verificar)
3. Backend envía email de verificación
4. Usuario hace clic en enlace del email
5. Frontend extrae token de la URL
6. Frontend llama /auth/verify-email con el token
7. Backend verifica el token y marca al usuario como verificado
8. Backend devuelve tokens de acceso y refresh
9. Frontend almacena tokens y redirige al dashboard

Relacionado

• Registrarse - Crear cuenta de usuario
• Reenviar Verificación - Obtener nuevo email de verificación
• Token Refresh - Refrescar token de acceso
• Login - Iniciar sesión con email y contraseña