Handheld Device Authentication with GrupoMAS Delegated Login

Handheld devices on GrupoMAS-integrated tenants use a delegated authentication flow. The warehouse operator submits their MAS credentials from the device; Dragon Guard validates the device authorization, then delegates credential verification directly to the GrupoMAS ERP. When MAS accepts the credentials, Dragon Guard issues its own JWT for the session. No local auth.Users row is created for delegated operators — MAS remains the identity authority while Dragon Guard remains the device authorization authority.

Prerequisites

Before a handheld device can authenticate, three conditions must be met:

Tenant must use GrupoMASNative integration

The device’s company record must have IntegrationMode = GrupoMASNative. Login is rejected with 409 auth.grupoMasNativeRequired for any other integration mode.

Device must be pre-authorized

The device key (normalized MAC address) must exist in the dbo.HandheldDevices table for the tenant and must have IsActive = true. Unregistered devices receive 403 plans.deviceNotAuthorized; inactive devices receive 403 plans.deviceInactive.

Company.Code must be populated

dbo.Companies.Code must be set on the tenant record. This value is used as codigo_empresa on all subsequent MAS product and stock queries. Login returns 501 integration.companyCodeRequired when it is missing.

Authenticates a warehouse operator against the GrupoMAS ERP and returns a Dragon Guard JWT scoped to the device’s tenant with the OPERATOR role.

Request body

username

string

required

The operator’s MAS username. Passed directly to the GrupoMAS authentication endpoint.

password

string

required

The operator’s MAS password in plaintext. Passed directly to the GrupoMAS authentication endpoint over HTTPS.

deviceId

string

required

The device’s MAC address or hardware identifier. The value is normalized to uppercase colon-separated format before lookup (e.g. aa-bb-cc-dd-ee-ff → AA:BB:CC:DD:EE:FF). Must match a pre-authorized entry in dbo.HandheldDevices.DeviceKey for the tenant.

deviceName

string

Human-readable label for the device (e.g. "Scanner-01"). When supplied, it updates the DeviceName field on the device record. Optional.

clientCode

string

Client or branch code forwarded to MAS during credential verification. Required only for MAS tenants that segment operators by client code. Optional.

Response fields

token

string

Signed HMAC SHA-256 JWT. Use as Authorization: Bearer <token> on all subsequent requests.

userId

string (UUID)

A deterministic UUID derived from GrupoMASNative:<companyId>:<username> via SHA-256. Stable across sessions for the same operator on the same tenant.

string

The email address returned by MAS, or the username value when MAS does not return an email.

fullName

string

The display name returned by MAS, or the username value when MAS does not return a name.

isSuperAdmin

boolean

Always false for handheld delegated sessions.

mustChangePassword

boolean

Always false for handheld delegated sessions. Password management remains in MAS.

isHandheld

boolean

Always true.

isExternalAuth

boolean

Always true for GrupoMAS delegated sessions.

authProvider

string

Always "GrupoMASNative" for this endpoint.

username

string

The normalized MAS username for the session (trimmed, as returned by MAS or the request value).

deviceId

string

The normalized device key (uppercase colon-separated MAC) that authenticated the session.

companyCode

string

The dbo.Companies.Code value for the device’s tenant. Used as codigo_empresa in subsequent MAS integration calls.

companyName

string

The display name of the device’s tenant (dbo.Companies.Name).

companies

array

Single-element array containing the device’s company and the OPERATOR role:

companyId (UUID)
roleCode: "OPERATOR"

Example

curl -s -X POST https://api.example.com/api/auth/grupomas-handheld-login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "operador01",
    "password": "MasPassword.1!",
    "deviceId": "AA:BB:CC:DD:EE:FF",
    "deviceName": "Scanner-01"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "email": "operador01",
  "fullName": "Operador Uno",
  "isSuperAdmin": false,
  "mustChangePassword": false,
  "isHandheld": true,
  "isExternalAuth": true,
  "authProvider": "GrupoMASNative",
  "username": "operador01",
  "deviceId": "AA:BB:CC:DD:EE:FF",
  "companyCode": "ATP",
  "companyName": "ATP Logistics S.A.",
  "companies": [
    {
      "companyId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "roleCode": "OPERATOR"
    }
  ]
}

Error responses

Status	Body / messageKey	Cause
`400`	`USERNAME_AND_PASSWORD_REQUIRED`	`username` or `password` is missing or blank.
`400`	`DEVICE_ID_REQUIRED`	`deviceId` is missing, blank, or normalizes to an empty string.
`401`	`auth.externalLoginFailed`	MAS rejected the supplied credentials.
`403`	`plans.deviceNotAuthorized`	No `dbo.HandheldDevices` record found for the normalized device key in this tenant.
`403`	`plans.deviceInactive`	The device record exists but `IsActive = false`.
`403`	`auth.companyInactive`	The device’s tenant is inactive (`IsActive = false` or `Status ≠ "Active"`).
`409`	`auth.grupoMasNativeRequired`	The tenant’s `IntegrationMode` is not `GrupoMASNative`.
`409`	`auth.localEmailConflict`	A local Dragon Guard user already exists with the same username. Use `/api/auth/login` instead.
`501`	`integration.adapterNotConfigured`	The GrupoMAS native adapter is not configured for the tenant (missing `BaseUrl` or similar).
`502`	`integration.remoteUnavailable`	Dragon Guard reached MAS but received an error response. The `remoteStatusCode` field gives details.
`503`	`LOGIN_TEMPORARILY_UNAVAILABLE`	An unexpected server error occurred. Retry with exponential back-off.

MAS endpoint compatibility

Dragon Guard supports both modern and legacy GrupoMAS site layouts. It attempts the modern endpoint first and falls back automatically:

Modern — POST /api/login with a JSON body. Used for current MAS deployments.
Legacy fallback — POST /Default.aspx/Ingresar with { usuario, pas, empresa, idioma }. Triggered when the modern endpoint returns 404 or 405. A successful legacy response has an empty mensaje field and a non-empty href field in response.d.

For legacy on-premise MAS environments, set the tenant BaseUrl to the site root (e.g. http://localhost:34670). Dragon Guard appends the correct path for each endpoint variant.

Device auto-registration

The X-Device-Id middleware runs on every authenticated request. When a request includes a device identifier that is not yet recorded in dbo.HandheldDevices, the middleware attempts best-effort registration. This allows devices to be implicitly registered during normal operation after an admin has pre-authorized them in the plan.

Auto-registration is best-effort and non-blocking — it will not fail a request if it encounters an error. Devices must still be explicitly authorized in the tenant’s device plan before the grupomas-handheld-login endpoint will accept them.

Device ID normalization

The raw deviceId value provided in the request is always normalized before use:

Whitespace is trimmed
All characters are uppercased
Hyphens (-) are replaced with colons (:)

For example, aa-bb-cc-dd-ee-ff becomes AA:BB:CC:DD:EE:FF. The normalized value is stored in the JWT deviceId claim and in dbo.HandheldDevices.DeviceKey. Ensure your device firmware sends the MAC in a consistent format to avoid mismatches.

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Handheld Device Authentication with GrupoMAS Delegated Login

Prerequisites

Request body

Response fields

Example

Error responses

MAS endpoint compatibility

Device auto-registration

Device ID normalization

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Prerequisites

​POST /api/auth/grupomas-handheld-login

​Request body

​Response fields

​Example

​Error responses

​MAS endpoint compatibility

​Device auto-registration

​Device ID normalization

Build docs developers (and LLMs) love

Prerequisites

POST /api/auth/grupomas-handheld-login

Request body

Response fields

Example

Error responses

MAS endpoint compatibility

Device auto-registration

Device ID normalization