Auth API Reference: Login, Register, and Token Endpoints

The Auth API handles all identity and session management for Dragon Guard WMS. It covers standard email/password login, GrupoMAS-delegated handheld login, self-service registration, and password change workflows for both web and handheld clients.

GET /api/auth/registration-options

Returns the list of active companies available for self-service registration and the default role code that will be assigned to new users. Authentication: None required.

companies

array

List of active companies available for registration selection.

Show Company object

string (uuid)

Unique company identifier.

name

string

Display name of the company.

defaultRoleCode

string

The role code (e.g., OPERATOR) that will be automatically assigned to newly registered users.

Error codes

Status	Meaning
200	Options returned successfully.

curl -X GET https://api.example.com/api/auth/registration-options

Authenticates a user by email and password. Optionally registers a handheld device when isHandheld is true. Returns a signed JWT along with user profile and company access list. Authentication: None required.

string

required

The user’s email address.

password

string

required

The user’s password.

isHandheld

boolean

Set to true when the request originates from a handheld/mobile device. Triggers device registration validation.

deviceId

string

Hardware device identifier. Required when isHandheld is true. Normalized to uppercase with : separators.

deviceName

string

Human-readable name for the device (e.g., Scanner-01). Optional.

token

string

Signed JWT for use in subsequent Authorization: Bearer headers.

userId

string (uuid)

Unique identifier of the authenticated user.

string

Authenticated user’s email address.

fullName

string

Authenticated user’s display name.

isSuperAdmin

boolean

Whether the user holds the SUPERADMIN_SUPREMO global role.

mustChangePassword

boolean

When true the UI must redirect the user to the change-password screen before continuing.

Companies

array

List of tenant company assignments for the authenticated user. Empty for super-admins.

Show Company access object

companyId

string (uuid)

The tenant’s company ID.

roleCode

string

The user’s role in that tenant (e.g., ADMIN, OPERATOR).

Error codes

Status	Code	Meaning
400	`EMAIL_AND_PASSWORD_REQUIRED`	Both fields must be non-empty.
401	`USER_NOT_FOUND`	No account matches the supplied email.
401	`INVALID_PASSWORD`	Password does not match the stored hash.
402	`plans.deviceLimitExceeded`	Active device count exceeds the tenant plan limit.
403	`plans.deviceNotAuthorized`	Device ID is not registered for this tenant.
403	`auth.companyInactive`	The user’s tenant is suspended or inactive.
409	`auth.userAssignedToOtherTenant`	The account is already tied to a different tenant.
503	`LOGIN_TEMPORARILY_UNAVAILABLE`	Unexpected server error; retry later.

curl -X POST https://api.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "S3cur3Pass!",
    "isHandheld": false
  }'

Delegates authentication to the GrupoMAS ERP system for handheld operators. The device must be pre-registered in Dragon Guard and the tenant must have IntegrationMode = GrupoMasNative. Credentials are forwarded to GrupoMAS and, on success, a Dragon Guard JWT is issued with role OPERATOR. Authentication: None required. The device key in deviceId is used to identify the tenant.

username

string

required

GrupoMAS operator username. Must not match any existing local Dragon Guard email.

password

string

required

GrupoMAS operator password.

deviceId

string

required

Hardware device identifier used to resolve the tenant. Normalized to uppercase colon format.

deviceName

string

Optional friendly name for the device.

clientCode

string

Optional GrupoMAS client/company code to pass alongside the authentication request.

token

string

Dragon Guard JWT with authProvider=GrupoMasNative.

userId

string (uuid)

Deterministic external user ID derived from provider, company, and username.

string

Normalized email or username used as the internal identity.

fullName

string

Display name returned by GrupoMAS (or username if not provided).

isHandheld

boolean

Always true for this endpoint.

isExternalAuth

boolean

Always true.

authProvider

string

Always GrupoMasNative.

username

string

Normalized GrupoMAS username.

deviceId

string

Normalized device key.

companyCode

string

Tenant company code sent to MAS on each request.

companyName

string

Tenant display name.

companies

array

Single-element array with the device’s company access.

Error codes

Status	Code	Meaning
400	`USERNAME_AND_PASSWORD_REQUIRED`	Both fields are mandatory.
400	`DEVICE_ID_REQUIRED`	Device ID is missing or empty after normalization.
401	`auth.externalLoginFailed`	GrupoMAS rejected the credentials.
403	`plans.deviceNotAuthorized`	Device not registered in Dragon Guard.
403	`plans.deviceInactive`	Device is disabled.
403	`auth.companyInactive`	Tenant is inactive.
409	`auth.localEmailConflict`	Username matches an existing local Dragon Guard account.
409	`auth.grupoMasNativeRequired`	Tenant is not configured for GrupoMASNative.
501	`integration.adapterNotConfigured`	GrupoMAS adapter not set up for this tenant.
502	`integration.remoteUnavailable`	GrupoMAS remote system returned an error.

curl -X POST https://api.example.com/api/auth/grupomas-handheld-login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jdoe",
    "password": "MasP@ss1",
    "deviceId": "AA:BB:CC:DD:EE:FF"
  }'

POST /api/auth/register

Creates a new user account and assigns it to a tenant. If the email already exists in another tenant the request is rejected. Password must satisfy complexity policy (≥8 chars, upper, lower, digit, special character). Authentication: None required.

string

required

User’s email address. Must match the tenant’s configured email domain if one is set.

password

string

required

Must be at least 8 characters and contain uppercase, lowercase, digit, and special character.

fullName

string

required

User’s display name.

companyId

string (uuid)

Target tenant. If omitted, the first available company from registration options is used.

message

string

Always USER_REGISTERED on success.

userId

string (uuid)

ID of the created or matched user.

companyId

string (uuid)

Tenant the user was assigned to.

role

string

Assigned role code (default role from registration options).

Error codes

Status	Code	Meaning
400	`MISSING_REQUIRED_FIELDS`	Email, password, or fullName is blank.
400	`PASSWORD_POLICY_NOT_MET`	Password doesn’t meet complexity requirements.
400	`NO_ACTIVE_COMPANY_AVAILABLE`	No active company found or provided.
400	`validation.companyRequired`	The supplied companyId does not exist.
400	`validation.emailDomainMismatch`	Email domain doesn’t match the tenant’s configured domain.
409	`auth.userAlreadyExistsInTenant`	Account already registered in this tenant.
409	`auth.userAssignedToOtherTenant`	Account belongs to a different tenant.

curl -X POST https://api.example.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "S3cur3Pass!",
    "fullName": "Jane Smith",
    "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

POST /api/auth/change-password

Changes the password for the currently authenticated user. Blocked for users whose account was authenticated via an external provider (e.g., GrupoMasNative). Authentication: Authorization: Bearer <token> (required).

currentPassword

string

required

The user’s existing password for verification.

newPassword

string

required

The desired new password. Must meet complexity policy.

message

string

Always PASSWORD_CHANGED on success.

Error codes

Status	Code	Meaning
400	`PASSWORD_REQUIRED`	One or both fields are missing.
400	`PASSWORD_POLICY_NOT_MET`	New password fails complexity check.
400	`CURRENT_PASSWORD_INVALID`	Current password is incorrect.
400	`auth.externalPasswordManaged`	Password is managed by external provider.
401	`INVALID_SESSION`	JWT is missing, expired, or userId claim is invalid.

curl -X POST https://api.example.com/api/auth/change-password \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "OldPass1!",
    "newPassword": "NewPass2@"
  }'

GET /api/auth/test

Returns the decoded claims from the caller’s JWT. Useful for verifying token content, company access, and role assignments during integration development. Authentication: Authorization: Bearer <token> (required).

message

string

Always OK.

userId

string (uuid)

User ID claim from the token.

companyId

string (uuid)

Primary company ID claim.

role

string

Global role claim (e.g., ADMIN, OPERATOR, SUPERADMIN_SUPREMO).

companies

array

List of company_access claims from the token.

companyRoles

array

List of company_role claims from the token.

curl -X GET https://api.example.com/api/auth/test \
  -H "Authorization: Bearer <token>"

Authentication

Warehouse Operations

RFID

Integration

Supreme

Auth API Reference: Login, Register, and Token Endpoints

GET /api/auth/registration-options

POST /api/auth/register

POST /api/auth/change-password

GET /api/auth/test

Build docs developers (and LLMs) love

Authentication

Warehouse Operations

RFID

Integration

Supreme

Documentation Index

​GET /api/auth/registration-options

​POST /api/auth/login

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

​POST /api/auth/register

​POST /api/auth/change-password

​GET /api/auth/test

Build docs developers (and LLMs) love

GET /api/auth/registration-options

POST /api/auth/login

POST /api/auth/grupomas-handheld-login

POST /api/auth/register

POST /api/auth/change-password

GET /api/auth/test