Skip to main content

​
POST /api/v1/auth/login

Authenticates a user with their credentials and returns JWT access and refresh tokens for subsequent API requests.

​
Request Body

​
username
string
required
The user’s username (must start with a letter, followed by letters, digits, dots, or dashes)
​
password
string
required
The user’s password (minimum 6 characters, maximum 100 characters)
​
platform
string
The platform from which the user is logging inOptions: web, android, ios
​
appVersion
string
The version of the application (maximum 50 characters)Example: 2.0.7
​
deviceId
string
A persistent UUID generated by the client to identify the device (maximum 255 characters)When provided, any previous tokens from this device will be automatically revoked.
​
deviceName
string
A human-readable name for the device (maximum 255 characters)Examples: Chrome · Windows, Samsung Galaxy S23

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
​
accessToken
string
JWT access token for authenticating API requestsInclude this token in the Authorization header as Bearer <accessToken>
​
refreshToken
string
JWT refresh token for obtaining new access tokens when they expireStore securely and use with the /api/v1/auth/refresh endpoint
​
user
object
​
id
string
The user’s unique identifier (UUID)
​
username
string
The user’s username
​
email
string | null
The user’s email address (optional)
​
role
string
The user’s role in the systemOptions: ADMIN, VENTANA, VENDEDOR
​
ventanaId
string | null
The ID of the ventana (window) associated with the user (null for ADMIN users)

​
Error Responses

​
401 Unauthorized
Invalid credentials provided
{
  "success": false,
  "message": "Invalid credentials"
}
​
403 Forbidden
User account is inactive
{
  "success": false,
  "message": "La cuenta está inactiva. Contacta al administrador.",
  "meta": "USER_INACTIVE"
}
​
400 Bad Request
Validation error in request body
{
  "success": false,
  "message": "Validation error",
  "errors": [
    {
      "field": "password",
      "message": "Password must be at least 6 characters long"
    }
  ]
}

curl -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "vendedor.1",
    "password": "securePassword123",
    "platform": "web",
    "appVersion": "2.0.7",
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceName": "Chrome · Windows"
  }'

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "vendedor.1",
      "email": "[email protected]",
      "role": "VENDEDOR",
      "ventanaId": "456e7890-e89b-12d3-a456-426614174001"
    }
  }
}

​
Notes

  • All login attempts are logged for security auditing purposes
  • If you provide a deviceId, any existing tokens for that device will be automatically revoked to maintain a single active session per device
  • The access token contains the user’s ID, role, ventanaId, and bancaId in its payload
  • Failed login attempts (wrong credentials, inactive account) are logged with detailed context including IP address and user agent
  • The IP address is extracted from the X-Forwarded-For header if present, otherwise from the request socket

Build docs developers (and LLMs) love

Get started for freeTalk to us