Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodexaCP/DG_BACK/llms.txt

Use this file to discover all available pages before exploring further.

Dragon Guard uses an explicit device authorization model — a handheld scanner can only log in to warehouse workflows if its MAC address has been pre-registered for the correct tenant. Authorization is managed by the Supreme administrator through the device management endpoints described below. The operational WMS modules enforce this check on every handheld login attempt; an unregistered or inactive device is always rejected before any credential verification occurs.

​
Device authorization model

Every physical scanner is represented by a record in core.HandheldDevices. The key fields that govern login eligibility are:
FieldDescription
MacAddress (DeviceKey)Normalized MAC address in AA:BB:CC:DD:EE:FF format (uppercase, colon-separated). This is the primary identifier Dragon Guard uses to recognize a device.
CompanyIdThe tenant this device belongs to. A MAC address can only be registered to one tenant at a time. Attempting to register the same MAC under a different tenant returns 409 Conflict with plans.devices.macInUse.
IsActiveControls whether login is currently permitted. false = device exists in the system but is blocked from logging in.
DeviceNameHuman-readable label for the device (e.g., Scanner 01, Dock Station). Required on upsert.
RfidDeviceProfileIdOptional link to an RFID device profile that defines how this scanner interacts with RFID-enabled warehouse operations.
FirstSeenAt / LastSeenAtTimestamps updated automatically by the X-Device-Id middleware on every authenticated request.
LastUserEmailThe email of the last user who authenticated from this device.
MAC addresses are normalized automatically by the API — hyphens are replaced with colons and all characters are converted to uppercase. You may submit aa-bb-cc-dd-ee-ff and it will be stored as AA:BB:CC:DD:EE:FF.

​
Device limit enforcement

Each tenant has a DeviceLimit that caps the number of simultaneously active devices. The effective limit is resolved in the following order:
  1. Company-level override — Companies.DeviceLimit if set (not null).
  2. Plan default — SaaSPlans.MaxHandheldDevices for the tenant’s assigned plan.
  3. System fallback — 1 if neither is configured.
The PUT endpoint enforces the limit against the number of devices in the submitted payload with isActive = true. You cannot save a device list where the active count exceeds the limit.
The minimum active device count is also enforced at 1. Submitting a payload where all devices have isActive = false returns 400 with plans.devices.minimumOne.

​
Handheld device endpoints

​
List devices for a tenant

GET /api/supreme/companies/{tenantId}/devices
Authorization: Bearer <supreme-jwt>
Returns all registered devices for the tenant, ordered by active status (active first) then device name. Response fields (per device):
​
id
guid
Internal device record ID.
​
deviceName
string
Friendly label assigned to the device.
​
macAddress
string
Normalized MAC address (AA:BB:CC:DD:EE:FF).
​
isActive
boolean
Whether this device is currently permitted to log in.
​
rfidDeviceProfileId
guid | null
ID of the assigned RFID device profile, if any.
​
rfidDeviceProfileCode
string | null
Code of the assigned RFID profile (e.g., RFID-STD).
​
rfidDeviceProfileName
string | null
Display name of the assigned RFID profile.
​
firstSeenAt
datetime
UTC timestamp of when the device first made an authenticated request.
​
lastSeenAt
datetime
UTC timestamp of the most recent authenticated request from this device.
​
lastUserEmail
string | null
Email address of the last user who logged in from this device.

​
Upsert (save) the device list

PUT /api/supreme/companies/{tenantId}/devices
Authorization: Bearer <supreme-jwt>
Content-Type: application/json
This is a batch upsert endpoint. The entire submitted list replaces the tenant’s current device roster. Devices present in the existing database but absent from the payload are deactivated (set to isActive = false), not deleted, preserving audit history. Request body: 
{
  "devices": [
    {
      "deviceName": "Scanner 01",
      "macAddress": "AA:BB:CC:DD:EE:FF",
      "isActive": true,
      "rfidDeviceProfileId": null
    },
    {
      "id": "existing-device-guid",
      "deviceName": "Dock Station",
      "macAddress": "11:22:33:44:55:66",
      "isActive": true,
      "rfidDeviceProfileId": "rfid-profile-guid"
    }
  ]
}
​
devices
array
required
List of device records to save.
Validation rules enforced before saving:
RuleError key
deviceName or macAddress is blank for any entryplans.devices.nameAndMacRequired
Duplicate MAC address within the submitted payloadplans.devices.duplicateMac
Active device count < 1plans.devices.minimumOne
Active device count > deviceLimitplans.devices.limitExceeded
Submitted id does not exist for this tenantplans.devices.invalidDevice
MAC address registered to a different tenantplans.devices.macInUse (409 Conflict)
RFID profile not found or inactive for this tenantplans.devices.invalidRfidDeviceProfile
Returns 204 No Content on success.

​
RFID profile assignment

An RFID device profile defines the scanning behavior and tag validation rules for a specific handheld scanner in RFID-enabled warehouse operations. Profiles are managed per-tenant under GET/POST/PUT /api/supreme/companies/{id}/integration/rfid-device-profiles. When assigning a profile to a device via the PUT devices endpoint:
  • The rfidDeviceProfileId must reference a profile belonging to the same tenant.
  • The profile must have isActive = true.
  • Passing null clears any existing profile assignment for that device.

​
Auto-registration and last-seen tracking

The X-Device-Id middleware inspects every authenticated request for a device identifier header. When a recognized device is seen, its LastSeenAt and LastUserEmail fields are updated automatically. This tracking happens passively — it does not grant login permission to unregistered devices. A device that sends requests but is not in core.HandheldDevices for the tenant is silently tracked at the middleware level, but login to handheld-specific workflows is blocked until explicit authorization is added through this API.

​
Login enforcement errors

The following error codes are returned during handheld login when device authorization checks fail:
HTTP StatusError KeyMeaning
403 Forbiddenplans.deviceNotAuthorizedThe device MAC address is not registered for this tenant.
403 Forbiddenplans.deviceInactiveThe device is registered but isActive = false.
402 Payment Requiredplans.deviceLimitExceededThe tenant’s active device count has reached or exceeded deviceLimit.
Plan suspension (Status = Suspended) blocks write operations across the WMS. Device login is subject to the same enforcement — suspended tenants cannot authorize new handheld sessions until their plan status is restored to Active.
The fastest way to get a scanner online for a new tenant is to include bootstrap.handheldDevice in the initial POST /api/supreme/companies request. The device is registered, named, and activated as part of the same atomic onboarding transaction. See Tenant Onboarding for the full bootstrap flow.

Build docs developers (and LLMs) love

Get started for freeTalk to us