Devices

Trusted device identities for agent sessions. A device is derived from a fingerprint (hostname, platform, arch, user-agent) the first time an agent session is created from it. Admins manage which devices may create sessions by setting each device's status.

Authentication

All device endpoints require a Bulwark-issued JWT with the admin role, plus the X-Bulwark-Tenant header.

Authorization: Bearer <adminToken>
X-Bulwark-Tenant: <tenant-id>

Device object

{
  "id": "dev_01j...",
  "tenant_id": "ten_01j...",
  "device_id": "fp_9a1c...",
  "name": "ci-runner-3",
  "hostname": "runner-3.internal",
  "platform": "linux",
  "arch": "amd64",
  "status": "active",
  "labels": { "team": "platform" },
  "last_seen_at": "2026-06-01T12:00:00Z",
  "created_at": "2026-05-01T00:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z"
}

status is one of active, suspended, revoked. device_id is the stable fingerprint identifier; id is the record's primary key (used in the routes below).

List Devices

GET /api/v1/devices

Response 200

{
  "devices": [
    { "id": "dev_01j...", "device_id": "fp_9a1c...", "name": "ci-runner-3", "status": "active", "...": "..." }
  ]
}

Get Device

GET /api/v1/devices/{id}

Response 200

Returns the device object directly (see above). 404 if not found.

Update Device Status

PATCH /api/v1/devices/{id}

Activates, suspends, or revokes a device. Suspended and revoked devices cannot create new agent sessions.

Body

{
  "status": "suspended"
}

status must be one of active, suspended, revoked.

Response 200

{ "status": "suspended" }

Returns 400 if status is not one of the allowed values.

Revoke Device

DELETE /api/v1/devices/{id}

Permanently revokes the device (equivalent to setting status revoked).

Response 200

{ "status": "revoked" }