Bulk Device Import & Offline Authentication

Who this is for: Administrators enrolling a batch of devices at once, either online (querying CyberRock live) or offline (using pre-computed credentials).

What you'll accomplish: Understand the import manifest, the difference between online and offline modes, and the fields each device entry needs.

Walkthrough videos for both flows are linked in the source SDK docs (a bulk-import video and an offline-authentication video).

Online vs offline mode

The mode is selected by whether you fill in the credentials:

Online import: leave HCW/HRW empty in cr_credentials. CyberRock is queried live for credentials during import.
Offline authentication: fill HCW/HRW. The pre-computed credentials in the file are used without a live CyberRock query.

Manifest fields

Field	Meaning
`batch_no` / `batch_description`	Identifier and free-text description of the import batch
`device_serial` / `TID`	The device serial number and the chip's unique Token ID (read via BIST, device menu option 0)
`device_status`	Initial lifecycle status; `A` = Active
`overwrite_existing`	`true` = update an existing record for the same TID; `false` = duplicates are rejected
`dev_display_name`	Human-readable device name shown in the frontend
`cr-linkage: tenant_id` / `group_id`	Your CyberRock tenant and the Device Group the imported devices join
`cr_credentials: HCW` / `HRW`	Pre-computed CyberRock challenge/response credentials. Empty = online import; filled = offline authentication
`cr-already_used`	Marks a credential pair as consumed; set `false` for new credentials
`profile_id`	The Device Profile (re-authentication policy) the devices inherit on enrollment

Online import manifest (HCW/HRW empty)

{   
    "batch_no": "BATCH-SAMPLE-001",   
    "batch_description": "Sample device import file",   
    "devices": [     
      {       
        "device": { "device_serial": "DEV-001-2025", "TID": "<TID>" },       
        "status": { "device_status": "A", "overwrite_existing": false },       
        "display": { "dev_display_name": "Online Gateway - Building A", "overwrite_existing": false },       
        "cr-linkage": {         
          "tenant_id": "<tenant-id>",         
          "group_id": "<group-id>",         
          "cr_credentials": [ { "HCW": "", "HRW": "", "cr-already_used": false } ],         
          "overwrite_existing": false       
      },       
      "profile": { "profile_id": 1, "overwrite_existing": false }     
    }   
  ] 
}

Offline authentication manifest (HCW/HRW filled)

The structure is the same, but each device carries its pre-computed credentials:

{   
    "batch_no": "BATCH-001",   
    "batch_description": "My device import",   
    "devices": [     
      {       
        "device": { "device_serial": "<TID>", "TID": "<TID>" },       
        "status": { "device_status": "A", "overwrite_existing": false },       
        "display": { "dev_display_name": "<TID>", "overwrite_existing": false },       
        "cr-linkage": {         
          "tenant_id": "<tenant-id>",         
          "group_id": "<group-id>",         
          "cr_credentials": [ { "HCW": "<HCW>", "HRW": "<HRW>", "cr-already_used": false } ],         
          "overwrite_existing": false       
      },       
      "profile": { "profile_id": 1, "overwrite_existing": false }     
    }   
  ] 
}

Add one object per device to the devices array.

Failure scenarios

A duplicate TID with overwrite_existing: false is rejected.
Invalid or already-used HCW/HRW credentials fail authentication for that device.
Malformed JSON rejects the whole batch.

You can also import via the REST API: POST /api/devices/bulk-import with the manifest as the body (see SDK User API & Code Examples).