POST /api/auth/login — authenticate a user

The login endpoint verifies the provided credentials against the database and, if valid, returns a signed JSON Web Token (JWT) alongside the user’s profile and their associated role permissions. You must include this token as a Bearer token in the Authorization header of every subsequent authenticated request.

Request

Method: POST
Path: /api/auth/login
Authentication: None required
Content-Type: application/json

Body parameters

string

The user’s email address. One of email, name, or code is required.

name

string

The user’s username. One of email, name, or code is required.

code

string

An alternative login code identifier. One of email, name, or code is required.

password

string

required

The user’s plaintext password. Compared against the stored bcrypt hash.

Exactly one identifier field (email, name, or code) must be present in the request body alongside password. Omitting all three returns a 400 validation error.

Response

200 — success

success

boolean

required

Always true on a successful response.

data

object

required

Hide properties

token

string

required

A signed JWT valid for 12 hours. Include this value as Authorization: Bearer <token> in all subsequent authenticated requests.

user

object

required

Show properties

string

Unique user identifier.

nombre

string

User’s first name.

apellido

string

User’s last name.

string

User’s email address.

cedula_rif

string

National ID or tax ID number.

telefono

string

Phone number.

cargo

string

Job title or position.

departamento

string

Department the user belongs to.

estatus

string

Account status (e.g. active).

last_activity

string

ISO 8601 timestamp of the user’s last activity.

created_at

string

ISO 8601 timestamp of account creation.

updated_at

string

ISO 8601 timestamp of the last profile update.

permisos

array

List of permission objects grouped by role assigned to the user. Empty array if no roles are assigned.

Examples

curl --request POST \
  --url http://localhost:7780/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "password": "s3cur3P@ss"
  }'

Success response

200

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "nombre": "María",
      "apellido": "González",
      "email": "[email protected]",
      "cedula_rif": "V-12345678",
      "telefono": "+58 412 555 0100",
      "cargo": "Analista",
      "departamento": "Tecnología",
      "estatus": "activo",
      "last_activity": "2024-06-01T10:30:00.000Z",
      "created_at": "2023-01-15T08:00:00.000Z",
      "updated_at": "2024-05-20T14:22:00.000Z"
    },
    "permisos": [
      {
        "rol": "editor",
        "permisos": ["read:reports", "write:reports"]
      }
    ]
  }
}

Error responses

401

{
  "message": "Credenciales inválidas."
}

400

{
  "errors": [
    {
      "message": "Se requiere al menos un identificador: email, username o code"
    },
    {
      "field": "password",
      "message": "La contraseña es requerida"
    }
  ]
}

500

{
  "message": "Error interno del servidor."
}

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

POST /api/auth/login — authenticate a user

Request

Body parameters

Response

200 — success

Examples

Success response

Error responses

Build docs developers (and LLMs) love

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​Request

​Body parameters

​Response

​200 — success

​Examples

​Success response

​Error responses

Build docs developers (and LLMs) love

Request

Body parameters

Response

200 — success

Examples

Success response

Error responses