Device Category Management

The Device Category Management APIs enable administrators to group physical access readers, turnstiles, locks, and IoT devices into logical categories (for example: HQ Exterior Turnstiles, Data Center Access, Parking Barriers).

Categories simplify policy assignment, access pass mapping, and reader telemetry across complex physical campuses.

---

Prerequisites

Before configuring device categories, ensure you have:

1. An administrator account with the Access Admin or Device Admin role.
2. A client application authorized with the following scopes:
   • cidaas:device_category_read
   • cidaas:device_category_write

---

Configuration & API Usage

1. Create a Device Category

To create a new category, send a POST request to the Device Category endpoint:

curl -X POST "https://your-tenant.cidaas.de/verification-srv/device-categories" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_name": "Data Center Secure Entry",
    "description": "High-security biometric and smart card readers for Server Room 1 & 2",
    "access_level": "RESTRICTED",
    "parent_category_id": "optional-parent-uuid"
  }'

2. List Device Categories (Graph / Hierarchy)

Retrieve all categories formatted as a hierarchical graph:

curl -X GET "https://your-tenant.cidaas.de/verification-srv/device-categories" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN"

3. Get Device Category by ID

curl -X GET "https://your-tenant.cidaas.de/verification-srv/device-categories/CATEGORY_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN"

4. Update a Device Category

curl -X PUT "https://your-tenant.cidaas.de/verification-srv/device-categories/CATEGORY_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_name": "Data Center Secure Entry (Phase 2)",
    "access_level": "HIGH_SECURITY"
  }'

5. Map Device Category to Resources (Physical Readers)

Link a physical reader or device to one or more categories:

curl -X POST "https://your-tenant.cidaas.de/verification-srv/device-categories/CATEGORY_ID/resources" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_ids": [
      "reader-turnstile-east-01",
      "reader-turnstile-east-02"
    ]
  }'

6. Delete a Device Category

curl -X DELETE "https://your-tenant.cidaas.de/verification-srv/device-categories/CATEGORY_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN"

---

Troubleshooting & Remediation

Issue	HTTP Status	Remediation
category_not_found	404	The requested category ID does not exist in the tenant database.
device_already_mapped	409	One or more specified devices are already assigned to this category.
category_has_active_devices	400 / 409	You cannot delete a category that still contains mapped devices. Unmap all devices first before deletion.