Skip to main content

​
POS Authentication

The POS Authentication API enables secure user authentication for Point of Sale systems using database credentials. Authentication is performed by verifying user credentials against the PostgreSQL database roles, and successful authentication returns a JWT token for subsequent authorized requests.

​
Endpoints Overview

MethodEndpointAuthenticationDescription
POST/api/pos/auth/loginNoneAuthenticate user and receive JWT token
GET/api/pos/auth/accessRequiredGet user’s role-based access permissions

​
POST /api/pos/auth/login

Authenticates a POS user using their database credentials. The endpoint attempts to establish a database connection with the provided credentials, retrieves the user’s role from PostgreSQL roles, and generates a JWT token upon successful authentication.

​
Request

​
user
string
required
The database username for authentication
​
password
string
required
The database password for authentication

​
Response

​
message
string
Status message indicating login success
​
token
string
JWT token for authenticated requests. Contains user credentials and role information.
​
role
string
The PostgreSQL role name assigned to the authenticated user

​
Example Request

curl -X POST http://localhost:3000/api/pos/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "user": "ventas_user",
    "password": "secure_password"
  }'

​
Response Examples

{
  "message": "Login exitoso",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c3VhcmlvIjoidmVudGFzX3VzZXIiLCJwYXNzd29yZCI6InNlY3VyZV9wYXNzd29yZCIsInJvbGUiOiJhZG1fdmVudGFzIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "role": "adm_ventas"
}

{
  "message": "user y password son requeridos"
}
This error occurs when either user or password fields are missing from the request body.
{
  "message": "Credenciales incorrectas o error de conexión",
  "detail": "password authentication failed for user \"ventas_user\""
}
Authentication failed due to invalid credentials or database connection issues. Verify that:
  • The username exists in the PostgreSQL database
  • The password is correct
  • The database server is accessible

​
Implementation Details

The login endpoint uses PostgreSQL role-based authentication. It queries the pg_roles and pg_auth_members system tables to determine the user’s role membership after successful authentication.
The JWT token contains:
  • usuario: The authenticated username
  • password: The user’s password (encrypted in token)
  • role: The PostgreSQL role name
  • Expiration time configured via JWT_EXPIRES_IN environment variable

​
GET /api/pos/auth/access

Retrieves the role-based access permissions for the authenticated user. This endpoint requires a valid JWT token and returns a permission matrix indicating which modules the user can access.
This endpoint requires authentication. Include the JWT token in the Authorization header.

​
Authentication

​
Authorization
string
required
Bearer token received from the login endpointExample: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Response

​
role
string
The user’s role name
​
access
object
Object containing boolean flags for each module permission

​
Example Request

curl -X GET http://localhost:3000/api/pos/auth/access \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Response Examples

{
  "role": "adm_ventas",
  "access": {
    "PRODUCTO": true,
    "MATERIA_PRIMA": false,
    "CLIENTE": true,
    "PROVEEDOR": false,
    "ESTANDAR": false,
    "FACTURA": true,
    "ORDENCOMPRA": false,
    "BODEGA": false
  }
}

{
  "role": "adm_bodega",
  "access": {
    "PRODUCTO": true,
    "MATERIA_PRIMA": true,
    "CLIENTE": false,
    "PROVEEDOR": false,
    "ESTANDAR": true,
    "FACTURA": false,
    "ORDENCOMPRA": false,
    "BODEGA": true
  }
}

{
  "role": "adm_compras",
  "access": {
    "PRODUCTO": false,
    "MATERIA_PRIMA": true,
    "CLIENTE": false,
    "PROVEEDOR": true,
    "ESTANDAR": false,
    "FACTURA": false,
    "ORDENCOMPRA": true,
    "BODEGA": false
  }
}

{
  "role": "admin",
  "access": {
    "PRODUCTO": true,
    "MATERIA_PRIMA": true,
    "CLIENTE": true,
    "PROVEEDOR": true,
    "ESTANDAR": true,
    "FACTURA": true,
    "ORDENCOMPRA": true,
    "BODEGA": true
  }
}

{
  "message": "Token inválido o expirado"
}
This error occurs when:
  • No Authorization header is provided
  • The token is invalid or malformed
  • The token has expired

​
Role Permissions Matrix

The following table shows the default access permissions for each role:
RoleProductoMateria PrimaClienteProveedorEstándarFacturaOrden CompraBodega
bodega / adm_bodega✓✓✗✗✓✗✗✓
ventas / adm_ventas / adm_fact✓✗✓✗✗✓✗✗
compras / adm_compras✗✓✗✓✗✗✓✗
admin / postgres✓✓✓✓✓✓✓✓
default✗✗✗✗✗✗✗✗

​
Error Codes

Status CodeDescription
200Request successful
400Bad request - missing required fields
401Unauthorized - invalid credentials or token
500Internal server error

​
Security Considerations

Important Security Notes:
  • JWT tokens contain sensitive credential information. Always use HTTPS in production.
  • Tokens expire based on the JWT_EXPIRES_IN environment variable configuration.
  • The authentication mechanism validates credentials directly against PostgreSQL roles.
  • Store tokens securely and never expose them in client-side code or logs.
For enhanced security, consider implementing:
  • Token refresh mechanisms
  • Rate limiting on login attempts
  • Audit logging for authentication events
  • Secure token storage practices (HttpOnly cookies, secure storage)

Build docs developers (and LLMs) love

Get started for freeTalk to us