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 Endpoints Registrar nuevo usuario Crea una cuenta de usuario nueva. Se envia un enlace de verificacion al email indicado.
Request Body: { "email" : "[email protected] " , "name" : "John Doe" , "password" : "SecurePassword123!" }
Nombre completo (minimo 2 caracteres)
Contrasena segura (minimo 8 caracteres)
Response: { "success" : true , "message" : "Registration successful. Please check your email to verify your account." , "user" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "email" : "[email protected] " , "name" : "John Doe" , "emailVerified" : false , "createdAt" : "2024-01-17T10:30:00Z" } }
Los usuarios deben verificar su email antes de acceder por completo a la plataforma.
Login Autentica al usuario y crea una sesion.
Request Body: Response: { "success" : true , "message" : "Login successful" , "user" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "email" : "[email protected] " , "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 Devuelve la informacion del usuario autenticado.
Headers: Response: { "user" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "email" : "[email protected] " , "name" : "John Doe" , "role" : "USER" , "emailVerified" : true , "createdAt" : "2024-01-17T10:30:00Z" } }
Renovar access token Obtiene un nuevo access token usando el refresh token.
Headers: Response: { "ok" : true , "user" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "email" : "[email protected] " , "name" : "John Doe" , "role" : "USER" } }
Cookies actualizados:
Nuevo accessToken
refreshToken rotado por seguridad
Logout Cierra sesion e invalida tokens.
Headers: Response: { "success" : true , "message" : "Logged out successfully" }
Cookies eliminados:
accessToken removidorefreshToken removido
Verificar email Verifica el email del usuario usando el token enviado por email.
Request Body: { "token" : "verification_token_from_email" }
Token de verificacion de email
Response: { "success" : true , "message" : "Email verified successfully. You can now log in." }
Reenviar verificacion de email /auth/send-email-verification
Solicita un nuevo email de verificacion si el anterior expiro o se perdio.
Request Body: Response: { "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 Solicita un enlace de restablecimiento via email.
Request Body: Response: { "success" : true , "message" : "If an account exists with this email, a password reset link has been sent." }
Por seguridad, la API siempre responde exito aunque el email no exista.
Restablecer contrasena Restablece la contrasena usando el token del email.
Request Body: { "token" : "reset_token_from_email" , "password" : "NewSecurePassword123!" }
Token de restablecimiento
Nueva contrasena (minimo 8 caracteres)
Response: { "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 minutosRefresh Token: 7 diasVerification Token: 24 horasReset Token: 1 hora
Codigos de error Code Status Descripcion INVALID_CREDENTIALS401 Email o contrasena incorrectos EMAIL_ALREADY_EXISTS409 Email ya registrado EMAIL_NOT_VERIFIED403 Se requiere verificacion de email INVALID_TOKEN400 Token invalido o expirado TOKEN_EXPIRED401 Token expirado WEAK_PASSWORD400 La contrasena no cumple requisitos RATE_LIMIT_EXCEEDED429 Demasiadas solicitudes
Casos de uso Ejemplo 1: Flujo completo de registro # Step 1: Register curl -X POST "https://api.steerai.autos/v1/auth/register" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "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": "[email protected] ", "password": "SecurePass123!" }'
Ejemplo 2: Flujo de restablecimiento de contrasena # Step 1: Request reset curl -X POST "https://api.steerai.autos/v1/auth/forgot-password" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] " }' # 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 # 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 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
Usa siempre HTTPS en produccion
Nunca transmitas credenciales por HTTP sin cifrado.
Implementa refresh de token en el cliente
Renueva tokens antes de que expiren para mantener la sesion.
Guarda refresh tokens de forma segura
Usa cookies HTTP-only (manejadas por la API) en lugar de localStorage.
Exige politicas fuertes de contrasenas
Requiere contrasenas con complejidad y longitud adecuadas.
Protege endpoints de autenticacion de ataques brute-force.
Registra eventos de autenticacion
Monitorea logins, resets de contrasena y actividad sospechosa.
Recursos relacionados 
