Auth Endpoints: Register, Login, and Password Reset

The Blackterz API provides four public authentication endpoints — no JWT is required to call any of them. Successful login and registration both return a signed JWT that must be included in all subsequent protected requests. All four endpoints are covered by the auth rate limiter (10 req / 15 min in production).

POST /api/auth/register

Create a new user account. The supplied password is hashed with bcrypt (10 salt rounds) before storage — the plaintext password is never persisted. Authentication: None required
Rate limited: Yes

Request Body

nombre

string

required

Display name for the new user.

string

required

Email address. Must be unique across all accounts and match the format [email protected].

password

string

required

Plaintext password. Must be at least 6 characters. Stored as a bcrypt hash — never returned in any response.

Responses

201 Created
400 Bad Request
409 Conflict

Account created successfully.

status

string

Always "ok" on success.

message

string

Human-readable confirmation: "Usuario registrado exitosamente".

data

object

Show data fields

integer

Auto-incremented ID of the newly created user.

nombre

string

Display name as provided.

string

Email address as provided.

{
  "status": "ok",
  "message": "Usuario registrado exitosamente",
  "data": {
    "id": 7,
    "nombre": "Ana García",
    "email": "[email protected]"
  }
}

Missing fields, invalid email format, or password shorter than 6 characters.

{
  "status": "error",
  "message": "Los campos nombre, email y password son requeridos"
}

{
  "status": "error",
  "message": "Formato de email inválido"
}

{
  "status": "error",
  "message": "La contraseña debe tener al menos 6 caracteres"
}

The email address is already registered.

{
  "status": "error",
  "message": "El email ya está registrado"
}

Example

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Ana García",
    "email": "[email protected]",
    "password": "secreto123"
  }'

Registration does not return a JWT. Call POST /api/auth/login immediately after registration to obtain a token.

Authenticate with email and password. Returns a signed JWT valid for 7 days. The token payload contains usuario_id, nombre, and email. Authentication: None required
Rate limited: Yes

Request Body

string

required

The registered email address.

password

string

required

The account password in plaintext. Verified against the stored bcrypt hash using bcrypt.compare().

Responses

200 OK
400 Bad Request
401 Unauthorized
403 Forbidden

Credentials valid and account active.

status

string

Always "ok" on success.

message

string

"Inicio de sesión exitoso".

data

object

Show data fields

token

string

Signed JWT. Include this in all subsequent protected requests as Authorization: Bearer <token>. Expires after 7 days.

usuario

object

Show usuario fields

integer

The authenticated user’s ID.

nombre

string

The user’s display name.

string

The user’s email address.

{
  "status": "ok",
  "message": "Inicio de sesión exitoso",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "usuario": {
      "id": 7,
      "nombre": "Ana García",
      "email": "[email protected]"
    }
  }
}

One or both required fields are missing.

{
  "status": "error",
  "message": "Los campos email y password son requeridos"
}

Email not found or password does not match. The message is intentionally generic to prevent email enumeration.

{
  "status": "error",
  "message": "Credenciales inválidas"
}

Credentials are correct but the account has been soft-deleted.

{
  "status": "error",
  "message": "Esta cuenta ha sido desactivada"
}

Example

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secreto123"
  }'

The JWT is valid for 7 days. After expiry, the middleware returns 401 with "Token expirado. Iniciá sesión nuevamente". Your client must redirect to login and obtain a fresh token.

POST /api/auth/forgot-password

Trigger a password reset email. If the supplied email belongs to an active account, a secure 64-character hex token is generated, stored with a 1-hour expiry, and emailed as a reset link. If the email is not found, the response is identical — this prevents account enumeration. Authentication: None required
Rate limited: Yes (shared auth limiter)

Request Body

string

required

The email address associated with the account to recover.

Responses

200 OK
400 Bad Request

Always returned regardless of whether the email exists.

{
  "ok": true,
  "mensaje": "Si el email existe, recibirás un correo con las instrucciones"
}

The email field was omitted entirely.

{
  "ok": false,
  "mensaje": "El email es obligatorio"
}

Reset Link Format

When an email is found and active, the user receives a message containing a link in the following format:

{APP_URL}/reset-password.html?token=<64-char-hex-token>

APP_URL defaults to http://localhost:3000 if the environment variable is not set. The token expires 1 hour after generation and is single-use.

Example

curl -X POST http://localhost:3000/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

The API always returns 200 for this endpoint. Do not use the response to infer whether an account exists.

POST /api/auth/reset-password

Set a new password using the token from the reset email. The token is validated against the password_resets table — it must exist, be unused, and not have passed its expira_en timestamp. On success, the token is immediately marked as used and cannot be reused. Authentication: None required
Rate limited: Yes (shared auth limiter)

Request Body

token

string

required

The 64-character hex token from the reset link query string (?token=...).

passwordNueva

string

required

The new plaintext password. Must be at least 8 characters. Hashed with bcrypt (10 rounds) before storage.

Responses

200 OK
400 Bad Request

Password updated and token consumed.

{
  "ok": true,
  "mensaje": "Contraseña actualizada. Ya podés iniciar sesión"
}

Missing fields, password too short, or invalid / expired / already-used token.

{
  "ok": false,
  "mensaje": "Token y nueva contraseña son obligatorios"
}

{
  "ok": false,
  "mensaje": "La nueva contraseña debe tener al menos 8 caracteres"
}

{
  "ok": false,
  "mensaje": "El enlace es inválido o ya expiró"
}

Example

curl -X POST http://localhost:3000/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a3f8c2e1b7d94f0c6a2e5b8d1f4c7a9e3b6d2f5a8c1e4b7d0f3a6c9e2b5d8f1",
    "passwordNueva": "nuevaContraseña123"
  }'

Reset tokens are single-use and expire after 1 hour. If a user clicks an already-used link or one that has timed out, they will receive a 400 response and must request a new reset email.

Overview

Endpoints

Auth Endpoints: Register, Login, and Password Reset

POST /api/auth/register

Request Body

Responses

Example

Request Body

Responses

Example

POST /api/auth/forgot-password

Request Body

Responses

Reset Link Format

Example

POST /api/auth/reset-password

Request Body

Responses

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/auth/register

​Request Body

​Responses

​Example

​POST /api/auth/login

​Request Body

​Responses

​Example

​POST /api/auth/forgot-password

​Request Body

​Responses

​Reset Link Format

​Example

​POST /api/auth/reset-password

​Request Body

​Responses

​Example

Build docs developers (and LLMs) love

POST /api/auth/register

Request Body

Responses

Example

POST /api/auth/login

Request Body

Responses

Example

POST /api/auth/forgot-password

Request Body

Responses

Reset Link Format

Example

POST /api/auth/reset-password

Request Body

Responses

Example