Authentication Endpoints

Overview

The TechStore API provides a complete authentication system with email verification, JWT-based authentication, and password recovery functionality. All authentication endpoints are publicly accessible and do not require authentication.

Register User

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "John",
    "apellido": "Doe",
    "email": "john.doe@example.com",
    "password": "securePassword123",
    "telefono": "555-0123",
    "direccion": "123 Main St, City, State"
  }'

Endpoint

method

string

default:"POST"

POST

endpoint

string

/api/auth/register

Request Body

nombre

string

required

User’s first name

apellido

string

User’s last name (max 100 characters)

string

required

User’s email address. Must be unique in the system

password

string

required

User’s password. Will be encrypted using BCrypt before storage

telefono

string

User’s phone number (max 20 characters)

direccion

string

User’s address (max 255 characters)

Response

message

string

Success message indicating the user should check their email for verification

Show Success Response (200 OK)

{
  "message": "Usuario registrado. Revisa tu correo para activar la cuenta."
}

Show Error Response (400 BAD REQUEST)

{
  "error": "Error al registrar: Email already exists"
}

Behavior

The password is automatically encrypted using BCrypt
A unique verification token (UUID) is generated and stored
User account is created with enabled: false status
A verification email with HTML design is sent to the provided email address
User cannot log in until email is verified

The email service runs asynchronously. If email sending fails, the user is still registered but won’t receive the verification email. Check server logs for email delivery issues.

Verify Account

curl -X GET "http://localhost:8080/api/auth/verificar?token=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Endpoint

method

string

default:"GET"

GET

endpoint

string

/api/auth/verificar

Query Parameters

token

string

required

The unique verification token sent to the user’s email during registration

Response

This endpoint returns HTML content, not JSON. It’s designed to be accessed directly from a browser via the email verification link.

Show Success Response (200 OK)

Returns a styled HTML page with:

Success message: “¡Cuenta activada con éxito!”
Confirmation that the account is now active
Link to login page

<html>
  <body style='font-family:sans-serif; text-align:center; padding:50px; background-color:#f4f7f6;'>
    <div style='background:white; padding:40px; border-radius:15px; display:inline-block;'>
      <h1 style='color: #28a745;'>¡Cuenta activada con éxito!</h1>
      <p style='color:#555;'>Gracias por confiar en <strong>Alexander Báez - Tienda Online</strong>.</p>
      <p>Ya puedes cerrar esta pestaña y volver a la tienda para iniciar sesión.</p>
      <a href='/login.html'>Ir al Login</a>
    </div>
  </body>
</html>

Show Error Response (400 BAD REQUEST)

Returns a styled HTML error page with:

Error message: “Error de activación”
Explanation that the link is invalid or already used

<html>
  <body style='font-family:sans-serif; text-align:center; padding:50px;'>
    <h1 style='color: #dc3545;'>Error de activación</h1>
    <p>El enlace es inválido o ya ha sido utilizado anteriormente.</p>
  </body>
</html>

Behavior

Validates the provided token against stored user tokens
If valid, sets user’s enabled field to true
Clears the verification token to prevent reuse
Returns visual HTML feedback suitable for browser display

Each verification token can only be used once. After successful verification, the token is invalidated.

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "password": "securePassword123"
  }'

Endpoint

method

string

default:"POST"

POST

endpoint

string

/api/auth/login

Request Body

string

required

User’s registered email address

password

string

required

User’s password (sent in plain text, compared against BCrypt hash)

Response

string

User’s unique identifier

access_token

string

JWT access token for authenticated requests. Valid for 10 hours (36000 seconds)

string

User’s email address

nombre

string

User’s first name

rol

string

User’s primary role (e.g., “ROLE_USER” or “ROLE_ADMIN”)

Show Success Response (200 OK)

{
  "id": "42",
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJzZWxmIiwic3ViIjoiam9obi5kb2VAZXhhbXBsZS5jb20iLCJleHAiOjE3MDk4NTYwMDAsImlhdCI6MTcwOTgyMDAwMCwic2NvcGUiOiJST0xFX1VTRVIifQ...",
  "email": "john.doe@example.com",
  "nombre": "John",
  "rol": "ROLE_USER"
}

Show Error Responses

400 BAD REQUEST - Missing required fields

{
  "status": 400,
  "error": "Bad Request",
  "message": "Datos incompletos"
}

404 NOT FOUND - User does not exist

{
  "status": 404,
  "error": "Not Found",
  "message": "Usuario no encontrado"
}

403 FORBIDDEN - Account not verified

{
  "status": 403,
  "error": "Forbidden",
  "message": "Tu cuenta no está activa. Revisa tu correo de Alexander Báez."
}

401 UNAUTHORIZED - Invalid password

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Contraseña incorrecta"
}

JWT Token Details

The access token is a signed JWT (JSON Web Token) with the following characteristics:

Token Algorithm

string

RSA256 (2048-bit RSA key pair)

Token Expiry

string

10 hours (36000 seconds) from issuance

Token Claims

object

Show Claims Structure

iss: “self” (issuer)
sub: User’s email address (subject)
iat: Issued at timestamp
exp: Expiration timestamp
scope: Space-separated roles (e.g., “ROLE_USER” or “ROLE_ADMIN”)

Using the JWT Token

Include the token in subsequent API requests using the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

The user must have verified their email (enabled=true) before they can successfully log in. Registration alone is not sufficient.

Forgot Password

curl -X POST http://localhost:8080/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com"
  }'

Endpoint

method

string

default:"POST"

POST

endpoint

string

/api/auth/forgot-password

Request Body

string

required

The email address of the account that needs password recovery

Response

message

string

Success message confirming recovery email was sent

error

string

Error message if the email was not found

Show Success Response (200 OK)

{
  "message": "Correo de recuperación enviado exitosamente."
}

Show Error Response (404 NOT FOUND)

{
  "error": "Email no encontrado."
}

Behavior

Checks if a user exists with the provided email address
Generates a new UUID token and stores it in the user’s tokenVerificacion field
Sends a recovery email with the token to the user’s email address
Returns success message (even if email sending fails, to prevent email enumeration)

The recovery token is stored in the same field as the verification token. This means requesting password recovery will invalidate any pending email verification tokens.

For security reasons, the API does not reveal whether an email exists in the system through different response times or messages. Always returns a success message if the request is properly formatted.

Reset Password

curl -X POST http://localhost:8080/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "nuevaPassword": "newSecurePassword456"
  }'

Endpoint

method

string

default:"POST"

POST

endpoint

string

/api/auth/reset-password

Request Body

token

string

required

The password reset token received via email from the forgot-password endpoint

nuevaPassword

string

required

The new password to set for the account. Will be encrypted using BCrypt before storage

Response

message

string

Success message confirming password update

error

string

Error message if token is invalid or expired

Show Success Response (200 OK)

{
  "message": "Tu contraseña ha sido actualizada correctamente."
}

Show Error Response (400 BAD REQUEST)

{
  "error": "El enlace ha expirado o es inválido."
}

Behavior

Validates the provided token against stored user tokens
Encrypts the new password using BCrypt
Updates the user’s password with the encrypted version
Clears the reset token to prevent reuse
Returns confirmation message

Each password reset token can only be used once. After successful password reset, the token is invalidated and cannot be reused.

Security Notes

The new password is automatically encrypted using BCrypt (same algorithm as registration)
No password strength validation is performed server-side (implement client-side validation)
Old sessions/tokens remain valid after password reset
Users should log in again with their new password

Authentication Flow

User Registration

User submits registration form with email and password

Password is encrypted with BCrypt
Verification token is generated
User record created with enabled: false
Verification email sent

Email Verification

User clicks verification link in email

Token is validated
Account is enabled (enabled: true)
User can now log in

User submits email and password

Credentials validated
Account enabled status checked
JWT token generated (10-hour expiry)
Token and user details returned

Authenticated Requests

User includes JWT token in requests

Token validated on each request
User roles/permissions checked
Protected resources accessed

Password Recovery Flow

Request Recovery

User submits forgot-password request with email

New recovery token generated
Recovery email sent with token

Reset Password

User clicks link and submits new password

Token validated
Password encrypted and updated
Token invalidated

User logs in with new credentials

New JWT token issued

Security Configuration

CORS Settings

The API accepts requests from the following origins:

http://localhost:63342
http://127.0.0.1:5500
http://127.0.0.1:63342
http://localhost:8080

Allowed methods: GET, POST, PUT, PATCH, DELETE, OPTIONS

Session Management

Session Policy: Stateless (no server-side sessions)
CSRF Protection: Disabled (using JWT tokens)
Authentication Type: JWT Bearer tokens

Public Endpoints

All /api/auth/** endpoints are publicly accessible and do not require authentication:

/api/auth/register
/api/auth/verificar
/api/auth/login
/api/auth/forgot-password
/api/auth/reset-password

Error Handling

All endpoints follow standard HTTP status codes:

Status Code	Meaning	Common Causes
200	Success	Request completed successfully
400	Bad Request	Missing required fields, invalid data format
401	Unauthorized	Invalid credentials, wrong password
403	Forbidden	Account not verified/enabled
404	Not Found	User/email not found in system
500	Internal Server Error	Database errors, unexpected exceptions

Error messages are returned in Spanish to match the application’s target audience. Consider this when building client applications.

Authentication

Resources

Authentication Endpoints

Overview

Register User

Endpoint

Request Body

Response

Behavior

Verify Account

Endpoint

Query Parameters

Response

Behavior

Endpoint

Request Body

Response

JWT Token Details

Using the JWT Token

Forgot Password

Endpoint

Request Body

Response

Behavior

Reset Password

Endpoint

Request Body

Response

Behavior

Security Notes

Authentication Flow

Password Recovery Flow

Security Configuration

CORS Settings

Session Management

Public Endpoints

Error Handling

Build docs developers (and LLMs) love

Authentication

Resources

​Overview

​Register User

​Endpoint

​Request Body

​Response

​Behavior

​Verify Account

​Endpoint

​Query Parameters

​Response

​Behavior

​Login

​Endpoint

​Request Body

​Response

​JWT Token Details

​Using the JWT Token

​Forgot Password

​Endpoint

​Request Body

​Response

​Behavior

​Reset Password

​Endpoint

​Request Body

​Response

​Behavior

​Security Notes

​Authentication Flow

​Password Recovery Flow

​Security Configuration

​CORS Settings

​Session Management

​Public Endpoints

​Error Handling

Build docs developers (and LLMs) love

Overview

Register User

Endpoint

Request Body

Response

Behavior

Verify Account

Endpoint

Query Parameters

Response

Behavior

Login

Endpoint

Request Body

Response

JWT Token Details

Using the JWT Token

Forgot Password

Endpoint

Request Body

Response

Behavior

Reset Password

Endpoint

Request Body

Response

Behavior

Security Notes

Authentication Flow

Password Recovery Flow

Security Configuration

CORS Settings

Session Management

Public Endpoints

Error Handling