Auth Endpoints: Login, Registration & Sessions

Dragon Guard uses a two-path login strategy: the handheld first attempts a GrupoMas-federated login, and automatically falls back to the standard local login when the tenant is standalone or the user identity exists locally. All four endpoints described here are public and do not require an Authorization header. Once a session is established, the returned token must be sent as a Bearer token on every subsequent protected request together with the X-Company-Id header matching the chosen company.

Authenticates a warehouse operator through the GrupoMas external identity provider. This is the primary login path on every handheld launch. If the server returns messageKey auth.localEmailConflict or auth.grupoMasNativeRequired, the client automatically retries using POST /api/auth/login with the same credentials — no user action is required.

The two-path strategy is transparent to the operator. The handheld always calls the GrupoMas endpoint first. A silent automatic retry to the local endpoint is triggered only when the server’s messageKey signals that the tenant is not federated or the user has a conflicting local account.

Method & path: POST /api/auth/grupomas-handheld-login
Auth required: No

Request body

{
  "username": "jdoe",
  "password": "s3cr3t",
  "deviceId": "AA:BB:CC:DD:EE:FF",
  "deviceName": "Zebra TC52 – Dock 3"
}

username

string

required

The operator’s GrupoMas username (maps to AuthLoginRequestDto.Email internally).

password

string

required

The operator’s password.

deviceId

string

Hardware identifier of the handheld device (MAC address or device serial). Required for device-authorization checks and plan-limit enforcement. If omitted, the server may reject the request with DEVICE_ID_REQUIRED.

deviceName

string

Human-readable label for the device, stored in the session audit log.

Response — 200 OK

{
  "token": "eyJhbGci...",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "[email protected]",
  "fullName": "John Doe",
  "companies": [
    {
      "companyId": "9c8b7a6f-...",
      "roleCode": "OPERATOR"
    }
  ]
}

token

string

JWT bearer token. Include this in Authorization: Bearer <token> on every protected request.

userId

guid

Internal UUID of the authenticated user.

string

Resolved email address for the authenticated identity.

fullName

string

Display name of the operator, shown in the handheld UI header.

companies

array

List of companies the user can access. The operator selects one; its companyId becomes the X-Company-Id header on protected requests.

Show AuthCompanyAccessDto

companyId

guid

Unique identifier of the company (tenant partition).

roleCode

string

Role assigned to the user within this company, e.g. OPERATOR, SUPERVISOR.

Error messageKeys

When the response is non-2xx and the body is JSON, the messageKey field drives the client error message. Possible values:

`messageKey`	Meaning
`auth.externalLoginFailed`	GrupoMas rejected the username or password.
`auth.localEmailConflict`	A local user with the same identifier exists — triggers automatic fallback to local login.
`auth.grupoMasNativeRequired`	Tenant is not configured for federated login — triggers automatic fallback to local login.
`auth.companyInactive`	The tenant is inactive.
`integration.adapterNotConfigured`	GrupoMas integration is not configured for this tenant.
`integration.remoteUnavailable`	GrupoMas service is unreachable or rejected the connection.
`integration.companyCodeRequired`	GrupoMas company code is missing from tenant configuration.
`plans.deviceNotAuthorized`	This device’s ID/MAC is not authorised for the tenant. The response body may include the resolved `deviceId`.
`plans.deviceInactive`	The device exists but is set to inactive.
`plans.deviceLimitExceeded`	The tenant has exceeded its plan’s active-device limit.

Plain-string (non-JSON) error codes:

Code	Meaning
`EMAIL_AND_PASSWORD_REQUIRED`	Credentials were not supplied.
`USERNAME_AND_PASSWORD_REQUIRED`	Credentials were not supplied.
`DEVICE_ID_REQUIRED`	`deviceId` field was absent or empty.
`USER_NOT_FOUND`	No matching user found.
`INVALID_USER`	User account is invalid or disabled.
`INVALID_PASSWORD`	Password does not match.
`LOGIN_TEMPORARILY_UNAVAILABLE`	Transient server-side failure.

Example

curl -X POST https://your-server/api/auth/grupomas-handheld-login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jdoe",
    "password": "s3cr3t",
    "deviceId": "AA:BB:CC:DD:EE:FF",
    "deviceName": "Zebra TC52 – Dock 3"
  }'

Standard local login endpoint. Used directly when the tenant is standalone, or reached automatically via the client’s fallback logic after grupomas-handheld-login returns auth.localEmailConflict or auth.grupoMasNativeRequired. The isHandheld flag tells the server this request originates from a physical handheld device. Method & path: POST /api/auth/login
Auth required: No

Request body

{
  "email": "[email protected]",
  "password": "s3cr3t",
  "deviceId": "AA:BB:CC:DD:EE:FF",
  "deviceName": "Zebra TC52 – Dock 3",
  "isHandheld": true
}

string

required

The operator’s local account email address.

password

string

required

The operator’s password.

deviceId

string

Hardware identifier of the handheld device.

deviceName

string

Human-readable label for the device.

isHandheld

boolean

Always true for requests originating from the Dragon Guard handheld client. Allows the server to apply handheld-specific session logic.

Response — 200 OK

Identical shape to POST /api/auth/grupomas-handheld-login. See Response fields above.

Error messageKeys

Same table as the GrupoMas login endpoint. The fallback keys auth.localEmailConflict and auth.grupoMasNativeRequired will not appear on this endpoint.

Example

curl -X POST https://your-server/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "s3cr3t",
    "deviceId": "AA:BB:CC:DD:EE:FF",
    "deviceName": "Zebra TC52 – Dock 3",
    "isHandheld": true
  }'

GET /api/auth/registration-options

Returns the list of companies available for self-registration and the default role code that will be assigned to new users. Call this endpoint to populate the company picker on the registration screen before submitting POST /api/auth/register. Method & path: GET /api/auth/registration-options
Auth required: No

Response — 200 OK

{
  "companies": [
    {
      "id": "9c8b7a6f-1234-5678-abcd-ef0123456789",
      "code": "ACME",
      "name": "Acme Warehousing S.A."
    }
  ],
  "defaultRoleCode": "OPERATOR"
}

companies

array

Companies available for self-registration.

Show AuthRegistrationCompanyDto

guid

Company UUID. Pass this as companyId in the registration request body.

code

string

Short alphanumeric company code, e.g. ACME.

name

string

Full company display name.

defaultRoleCode

string

Role code assigned to newly registered users. Defaults to OPERATOR.

Example

curl https://your-server/api/auth/registration-options

POST /api/auth/register

Creates a new local user account within the specified company. On success, the server returns 200 OK with no response body. The new user can immediately log in with POST /api/auth/login.

Self-registration is only available when the tenant allows it. If GET /api/auth/registration-options returns an empty companies array, registration is disabled.

Method & path: POST /api/auth/register
Auth required: No

Request body

{
  "email": "[email protected]",
  "password": "Str0ngP@ssw0rd",
  "fullName": "María García",
  "companyId": "9c8b7a6f-1234-5678-abcd-ef0123456789"
}

string

required

Email address for the new account. Must be unique within the tenant.

password

string

required

Password for the new account. Minimum strength requirements are enforced server-side.

fullName

string

required

Full display name of the new user, shown in the handheld UI header after login.

companyId

guid

UUID of the company to associate with the new user. Obtain valid values from GET /api/auth/registration-options. If omitted, the server may assign a default or return an error.

Response — 200 OK

No response body. A successful 200 indicates the account was created. Proceed to POST /api/auth/login.

Example

curl -X POST https://your-server/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Str0ngP@ssw0rd",
    "fullName": "María García",
    "companyId": "9c8b7a6f-1234-5678-abcd-ef0123456789"
  }'

API Endpoints

Services

Data Models

Auth Endpoints: Login, Registration & Sessions

Request body

Response — 200 OK

Error messageKeys

Example

Request body

Response — 200 OK

Error messageKeys

Example

GET /api/auth/registration-options

Response — 200 OK

Example

POST /api/auth/register

Request body

Response — 200 OK

Example

Build docs developers (and LLMs) love

API Endpoints

Services

Data Models

Documentation Index

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

​Request body

​Response — 200 OK

​Error messageKeys

​Example

​POST /api/auth/login

​Request body

​Response — 200 OK

​Error messageKeys

​Example

​GET /api/auth/registration-options

​Response — 200 OK

​Example

​POST /api/auth/register

​Request body

​Response — 200 OK

​Example

Build docs developers (and LLMs) love

POST /api/auth/grupomas-handheld-login

Request body

Response — 200 OK

Error messageKeys

Example

POST /api/auth/login

Request body

Response — 200 OK

Error messageKeys

Example

GET /api/auth/registration-options

Response — 200 OK

Example

POST /api/auth/register

Request body

Response — 200 OK

Example