POST /api/v1/auth/register — Register a New User

The POST /api/v1/auth/register endpoint creates a new user account in the system. It validates the request body against registerSchema, hashes the provided password using bcrypt with 12 salt rounds, and stores the user record with the specified role. The response returns the created user object with the password field removed. No authentication token is required to call this endpoint.

Endpoint

POST /api/v1/auth/register

Base URL: http://localhost:{PORT}/api/v1 Authentication: None required

Request Body

full_name

string

required

The user’s full display name. Must be between 2 and 100 characters.

string

required

The user’s email address. Must match the pattern user@domain.tld. This value must be unique — the API returns 409 if the email is already registered.

password

string

required

The user’s plain-text password. Must be between 6 and 100 characters. It is never stored or returned in plain text.

roleId

number

required

The numeric ID of an existing role to assign to this user (foreign key to the roles table). Providing a non-existent roleId returns a 400 error due to a foreign key constraint violation (ER_NO_REFERENCED_ROW_2).

The password field is hashed with bcrypt using 12 salt rounds (SALT_ROUNDS = 12) before being written to the database. The hashed value is never included in any API response.

Example Request

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "password": "securePass123",
    "roleId": 2
  }'

Responses

201 Created

Returned when the user is successfully registered. The response body contains the new user record with the password field omitted.

{
  "success": true,
  "message": "Usuario registrado exitosamente",
  "data": {
    "idUser": 7,
    "full_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "roleId": 2
  }
}

success

boolean

Always true for successful responses.

message

string

Human-readable confirmation message: "Usuario registrado exitosamente".

data

object

The newly created user record.

Show data fields

data.idUser

number

Auto-incremented primary key assigned to the new user.

data.full_name

string

The full name provided in the request body.

data.email

string

The email address provided in the request body.

data.roleId

number

The role ID assigned to the user.

400 Bad Request — Validation Error

Returned when one or more required fields are missing, fail type checks, or violate length/pattern constraints (enforced by validate.middleware against registerSchema). Also returned when the provided roleId does not reference a valid role (MySQL ER_NO_REFERENCED_ROW_2 foreign key violation).

{
  "success": false,
  "message": "El campo 'email' debe tener un formato de correo válido",
  "data": null
}

409 Conflict — Email Already Registered

Returned when the supplied email already exists in the users table. The service checks for a duplicate before inserting (ER_DUP_ENTRY).

{
  "success": false,
  "message": "El correo ya está registrado",
  "data": null
}

Socket.IO Events

During registration the service emits real-time progress events on the auth:register channel. Clients connected to the Socket.IO server receive these in sequence:

Order	Status	Payload message
1	`start`	`"Iniciando registro de usuario..."`
2	`processing`	`"Verificando disponibilidad del correo..."`
3	`processing`	`"Procesando contraseña..."`
4	`processing`	`"Guardando usuario..."`
5	`success`	`"Usuario registrado exitosamente"`

// Client-side listener example
socket.on("auth:register", (event) => {
  console.log(event.status, event.message);
  // { status: "processing", message: "Verificando disponibilidad del correo..." }
});

Auth

Users

Roles

Permissions

Sidebar

POST /api/v1/auth/register — Register a New User

Endpoint

Request Body

Example Request

Responses

201 Created

400 Bad Request — Validation Error

409 Conflict — Email Already Registered

Socket.IO Events

Build docs developers (and LLMs) love

Auth

Users

Roles

Permissions

Sidebar

Documentation Index

​Endpoint

​Request Body

​Example Request

​Responses

​201 Created

​400 Bad Request — Validation Error

​409 Conflict — Email Already Registered

​Socket.IO Events

Build docs developers (and LLMs) love

Endpoint

Request Body

Example Request

Responses

201 Created

400 Bad Request — Validation Error

409 Conflict — Email Already Registered

Socket.IO Events