RFID Operation Policies and Device Profile Configuration

Two configuration layers govern how RFID behaves at runtime. Operation policies define the rules — which modules use RFID, what the operating mode is, when to block and when to fall back. Device profiles describe the hardware — vendor, reader transport, RFID and barcode capabilities, power defaults. At runtime these two layers are combined into a single handheld context response that the APK consumes to initialise the reader and decide which capture paths are available.

Both operation policies and device profiles are administered by SUPERADMIN_SUPREMO through the Supreme portal. Handheld devices consume them read-only at runtime.

Operation policies

An RfidOperationPolicy record controls RFID behaviour for a specific warehouse module within a tenant. One active policy per (CompanyId, PolicyScope, Module) is enforced to avoid ambiguity.

Managing policies (Supreme)

Method	Endpoint	Description
`GET`	`/api/supreme/companies/{id}/integration/rfid-policies`	List all RFID operation policies for the tenant
`PUT`	`/api/supreme/companies/{id}/integration/rfid-policies`	Create or update (upsert) the policy for a module

Supported modules

Items · Receipts · Shipments · Movements

Policy fields

The following fields map directly to the RfidOperationPolicy entity and are surfaced through RfidEffectivePolicyDto at runtime.

Field	Type	Description
`module`	`string`	Warehouse module this policy governs
`mode`	`string`	Operating mode: `Disabled`, `InquiryOnly`, `OperationalAssist`, `StrictValidation`
`isEnabled`	`bool`	Whether RFID is active for this module
`allowManualFallback`	`bool`	Permit the operator to skip RFID and enter data manually
`allowBarcodeFallback`	`bool`	Permit the operator to switch to barcode scanning when RFID is unavailable
`blockOnUnknownTag`	`bool`	Block the operation when the scanned EPC is not in the registry
`blockOnInactiveTag`	`bool`	Block the operation when the matched tag has `IsActive = false`
`blockOnValidationMismatch`	`bool`	Block the operation when the EPC resolves to a different item than expected
`requireRfidEvidence`	`bool`	Require at least one valid RFID read before the operation can be completed
`recordAuditEvents`	`bool`	Persist every tag read as an `RfidScanEvent`
`duplicateReadWindowSeconds`	`int?`	Ignore subsequent reads of the same EPC within this window (seconds)
`maxReadsPerOperation`	`int?`	Cap the number of RFID reads accepted in a single operation
`unknownTagBehavior`	`string`	`Allow`, `Warn`, or `Block` — fine-grained control over unknown-tag handling
`duplicateTagBehavior`	`string`	`Allow`, `Warn`, or `Block` — fine-grained control over duplicate-read handling
`notes`	`string?`	Free-text administrator notes

Effective policy DTO (`RfidEffectivePolicyDto`)

When the handheld calls the context endpoint, the resolved policy is returned as an RfidEffectivePolicyDto. This object carries the same fields as above plus resolution metadata:

Field	Type	Description
`success`	`bool`	Whether the policy was resolved successfully
`isRfidEnabled`	`bool`	Whether RFID is enabled globally for the tenant
`isModuleEnabled`	`bool`	Whether RFID is enabled specifically for this module
`effectiveMode`	`string`	The resolved operating mode
`policySource`	`string`	How the policy was resolved (e.g. `MODULE_POLICY`, `TENANT_DISABLED`)
`policyScope`	`string?`	Scope of the matched policy record
`message`	`string?`	Human-readable explanation when resolution falls back to defaults
`duplicateReadWindowSeconds`	`int`	Effective duplicate suppression window (0 if not set)
`unknownTagBehavior`	`string`	Defaults to `ALLOW` if not configured
`duplicateTagBehavior`	`string`	Defaults to `ALLOW` if not configured

Behavior values

Allow

The condition is accepted silently and the operation continues. Use Allow when you want to be permissive during rollout or in low-risk modules.

Warn

The condition is logged and a warning is surfaced to the operator on the handheld, but the operation is not blocked. Suitable for OperationalAssist mode where awareness matters but throughput must not be interrupted.

Block

The condition halts the operation. The operator must resolve the discrepancy — through a supervisor override, correct tag scan, or fallback path — before continuing. Use Block in StrictValidation mode.

Effective policy for a handheld

The handheld application does not call the Supreme endpoint directly. It calls:

GET /api/rfid/handheld/context?module={module}

This returns the fully resolved RfidEffectivePolicyDto embedded in the runtime context (see Handheld runtime context below).

Device profiles

An RfidDeviceProfile describes a family of handheld readers — not a specific authorised device. Profiles are managed at the tenant level. Each authorised HandheldDevice record can optionally reference one profile; devices without a profile still operate normally for barcode and manual workflows.

Managing profiles (Supreme)

Method	Endpoint	Description
`GET`	`/api/supreme/companies/{id}/integration/rfid-device-profiles`	List all device profiles for the tenant
`POST`	`/api/supreme/companies/{id}/integration/rfid-device-profiles`	Create a new device profile
`PUT`	`/api/supreme/companies/{id}/integration/rfid-device-profiles/{profileId}`	Update an existing profile

Profile fields

Field	Type	Description
`code`	`string`	Short internal identifier (e.g. `ZEBRA-TC52`)
`name`	`string`	Human-readable display name
`vendor`	`string`	Hardware vendor (e.g. `Zebra`, `Honeywell`)
`model`	`string`	Device model name or number
`platform`	`string`	OS / SDK platform (e.g. `Android`, `Windows`)
`connectionType`	`string`	How the reader connects (e.g. `INTEGRATED`, `BLUETOOTH`, `USB`)
`supportsRfid`	`bool`	Whether the device has an RFID reader
`supportsBarcode`	`bool`	Whether the device has a barcode scanner
`readerTransport`	`string?`	RFID reader transport layer (e.g. `SERIAL`, `USB_HID`)
`triggerMode`	`string?`	How the scan is triggered: `TRIGGER_PULL`, `CONTINUOUS`, `SCHEDULED`
`defaultPowerLevel`	`int?`	Default reader transmit power (dBm)
`defaultTimeoutMs`	`int?`	Default read timeout in milliseconds
`defaultInventoryMode`	`string?`	Default inventory algorithm (e.g. `SINGLE`, `MULTI`)
`capabilitiesJson`	`string?`	Free-form JSON describing extended hardware capabilities
`settingsJson`	`string?`	Free-form JSON for device-specific SDK settings
`isDefault`	`bool`	Whether this is the tenant-fallback profile when no device-level assignment exists
`isActive`	`bool`	Whether the profile is available for assignment

Profile resolution order

When a handheld calls any RFID endpoint, Dragon Guard resolves the effective device profile using the following priority:

Device-assigned profile

If the HandheldDevice record has an explicit RfidDeviceProfileId, that profile is used.

Tenant default profile

If no device-level assignment exists, Dragon Guard looks for the active profile with IsDefault = true for the tenant.

No profile

If neither applies, hasProfile = false is returned. The device can still operate in barcode and manual modes according to policy.

Effective profile endpoint

GET /api/rfid/device-profile/effective

Resolves the effective RfidEffectiveDeviceProfileDto for the calling handheld. Pass the device identifier in the X-Device-Id header or let the endpoint read it from the JWT claim deviceId.

Header	Required	Description
`X-Device-Id`	Optional	Override device ID; falls back to JWT `deviceId` claim

Effective profile response fields (`RfidEffectiveDeviceProfileDto`)

success

bool

Whether the profile resolution call succeeded.

hasProfile

bool

Whether a device profile was resolved for this device.

supportsRfid

bool

true if the resolved profile has supportsRfid = true.

supportsBarcode

bool

true if the resolved profile has supportsBarcode = true.

resolutionSource

string

How the profile was resolved: DEVICE_PROFILE, TENANT_DEFAULT, NO_PROFILE, or DEVICE_NOT_AUTHORIZED.

deviceId

string?

The device identifier that was used for resolution.

handheldDeviceId

guid?

Internal ID of the matched HandheldDevice record.

rfidDeviceProfileId

guid?

Internal ID of the resolved RfidDeviceProfile record.

code

string?

Profile code (e.g. ZEBRA-TC52).

name

string?

Profile display name.

vendor

string?

Hardware vendor.

model

string?

Device model.

platform

string?

OS / SDK platform.

connectionType

string?

Reader connection type.

readerTransport

string?

RFID reader transport layer.

triggerMode

string?

Scan trigger mode.

defaultPowerLevel

int?

Default transmit power in dBm.

defaultTimeoutMs

int?

Default read timeout in milliseconds.

defaultInventoryMode

string?

Default inventory algorithm.

capabilitiesJson

string?

JSON string with extended hardware capabilities.

settingsJson

string?

JSON string with device-specific SDK settings.

isDefault

bool

Whether this profile is the tenant-wide default.

message

string?

Human-readable explanation when resolution could not find a profile.

Handheld runtime context

The single most important RFID endpoint for mobile integrations combines both the effective policy and the effective device profile into one response.

GET /api/rfid/handheld/context?module={module}

Query parameter	Required	Description
`module`	✓	Warehouse module to resolve policy for: `Items`, `Receipts`, `Shipments`, `Movements`

Header	Required	Description
`X-Device-Id`	Optional	Override device ID; falls back to JWT `deviceId` claim

Response fields (`RfidHandheldRuntimeContextDto`)

success

bool

Whether the context was resolved successfully.

module

string

The module that was requested.

deviceId

string

The device identifier that was used for resolution.

isDeviceAuthorized

bool

Whether the calling device is recognised as an authorised handheld in the tenant.

hasDeviceProfile

bool

Whether a device profile was resolved for this device.

supportsRfid

bool

Whether the resolved device profile declares RFID hardware support.

supportsBarcode

bool

Whether the resolved device profile declares barcode scanner support.

rfidEnabledForModule

bool

true when both the global RFID setting and the module policy have RFID enabled.

canUseRfid

bool

true when the policy enables RFID for the module and the device profile confirms RFID hardware is present.

canFallbackToManual

bool

true when the active policy permits manual data entry as a fallback.

canFallbackToBarcode

bool

true when the active policy permits barcode scanning as a fallback and the device supports barcode.

canOperateWithoutRfid

bool

true when either canFallbackToManual or canFallbackToBarcode is true.

rfidHardwareStatus

string

Summarises why RFID is or is not usable on this device. Possible values:

Value	Meaning
`READY`	RFID is enabled by policy and the device has a working reader
`NO_RFID_PROFILE`	No device profile has been assigned or resolved
`RFID_NOT_SUPPORTED`	The resolved profile explicitly sets `supportsRfid = false`
`RFID_DISABLED_BY_POLICY`	A profile exists but the module policy has RFID disabled
`DEVICE_NOT_AUTHORIZED`	The device is not registered as an authorised handheld

deviceResolutionSource

string

How the device profile was resolved (mirrors resolutionSource in RfidEffectiveDeviceProfileDto).

policySource

string

How the policy was resolved (mirrors policySource in RfidEffectivePolicyDto).

effectiveMode

string

The resolved operating mode for this module: Disabled, InquiryOnly, OperationalAssist, or StrictValidation.

message

string?

Human-readable explanation surfaced from either the policy or profile resolver.

policy

RfidEffectivePolicyDto

The full resolved policy object for the requested module.

deviceProfile

RfidEffectiveDeviceProfileDto

The full resolved device profile object.

Example

curl "https://api.dragonguard.io/api/rfid/handheld/context?module=Receipts" \
  -H "Authorization: Bearer <token>" \
  -H "X-Device-Id: DEVICE-001"

{
  "success": true,
  "module": "Receipts",
  "deviceId": "DEVICE-001",
  "isDeviceAuthorized": true,
  "hasDeviceProfile": true,
  "supportsRfid": true,
  "supportsBarcode": true,
  "rfidEnabledForModule": true,
  "canUseRfid": true,
  "canFallbackToManual": false,
  "canFallbackToBarcode": true,
  "canOperateWithoutRfid": true,
  "rfidHardwareStatus": "READY",
  "deviceResolutionSource": "DEVICE_PROFILE",
  "policySource": "MODULE_POLICY",
  "effectiveMode": "StrictValidation",
  "message": null,
  "policy": {
    "success": true,
    "isRfidEnabled": true,
    "isModuleEnabled": true,
    "module": "Receipts",
    "effectiveMode": "StrictValidation",
    "policySource": "MODULE_POLICY",
    "allowManualFallback": false,
    "allowBarcodeFallback": true,
    "blockOnUnknownTag": true,
    "blockOnInactiveTag": true,
    "blockOnValidationMismatch": true,
    "requireRfidEvidence": true,
    "recordAuditEvents": true,
    "duplicateReadWindowSeconds": 5,
    "maxReadsPerOperation": null,
    "unknownTagBehavior": "Block",
    "duplicateTagBehavior": "Warn"
  },
  "deviceProfile": {
    "success": true,
    "hasProfile": true,
    "supportsRfid": true,
    "supportsBarcode": true,
    "resolutionSource": "DEVICE_PROFILE",
    "deviceId": "DEVICE-001",
    "code": "ZEBRA-TC52",
    "vendor": "Zebra",
    "model": "TC52",
    "platform": "Android",
    "connectionType": "INTEGRATED",
    "isDefault": false
  }
}

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

RFID Operation Policies and Device Profile Configuration

Operation policies

Managing policies (Supreme)

Supported modules

Policy fields

Effective policy DTO (`RfidEffectivePolicyDto`)

Behavior values

Effective policy for a handheld

Device profiles

Managing profiles (Supreme)

Profile fields

Profile resolution order

Effective profile endpoint

Effective profile response fields (`RfidEffectiveDeviceProfileDto`)

Handheld runtime context

Response fields (`RfidHandheldRuntimeContextDto`)

Example

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Operation policies

​Managing policies (Supreme)

​Supported modules

​Policy fields

​Effective policy DTO (RfidEffectivePolicyDto)

​Behavior values

​Effective policy for a handheld

​Device profiles

​Managing profiles (Supreme)

​Profile fields

​Profile resolution order

​Effective profile endpoint

​Effective profile response fields (RfidEffectiveDeviceProfileDto)

​Handheld runtime context

​Response fields (RfidHandheldRuntimeContextDto)

​Example

Build docs developers (and LLMs) love

Operation policies

Managing policies (Supreme)

Supported modules

Policy fields

Effective policy DTO (`RfidEffectivePolicyDto`)

Behavior values

Effective policy for a handheld

Device profiles

Managing profiles (Supreme)

Profile fields

Profile resolution order

Effective profile endpoint

Effective profile response fields (`RfidEffectiveDeviceProfileDto`)

Handheld runtime context

Response fields (`RfidHandheldRuntimeContextDto`)

Example