Devices API

The Devices API allows you to manage device enrollment, monitor device status, and perform administrative actions like remote wipe.

Device Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org-123",
  "user_id": "user-456",
  "device_name": "John's Laptop",
  "platform": "linux",
  "agent_version": "1.0.0",
  "status": "online",
  "last_seen": "2026-02-12T10:30:00Z",
  "enrolled_at": "2026-02-01T09:00:00Z",
  "policy_id": "policy-789",
  "vpn_ip": "10.100.0.15",
  "created_at": "2026-02-01T09:00:00Z",
  "updated_at": "2026-02-12T10:30:00Z"
}

Device Status Values

Status Description
online Device is connected and active
offline Device has not checked in recently
suspended Device is temporarily disabled
wiped Work profile has been wiped
pending Enrollment in progress

Supported Platforms

  • linux - Linux (Ubuntu, Fedora, Arch, etc.)
  • windows - Windows 10/11
  • macos - macOS 12+
  • android - Android 10+
  • ios - iOS 15+

List Devices

GET /api/v1/devices

Retrieve a paginated list of devices in your organization.

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
page_size integer Items per page (default: 20, max: 100)
status string Filter by status
platform string Filter by platform
user_id string Filter by user

Request

GET /api/v1/devices?status=online&platform=linux&page=1&page_size=20
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "device_name": "John's Laptop",
      "platform": "linux",
      "status": "online",
      "last_seen": "2026-02-12T10:30:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "page_size": 20,
  "total_pages": 3
}

Get Device

GET /api/v1/devices/:id

Retrieve details of a specific device.

GET /api/v1/devices/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org-123",
  "user_id": "user-456",
  "device_name": "John's Laptop",
  "platform": "linux",
  "agent_version": "1.0.0",
  "status": "online",
  "last_seen": "2026-02-12T10:30:00Z",
  "enrolled_at": "2026-02-01T09:00:00Z",
  "policy_id": "policy-789",
  "vpn_ip": "10.100.0.15",
  "compliance": {
    "status": "compliant",
    "last_check": "2026-02-12T10:00:00Z",
    "violations": []
  }
}

Enroll Device

POST /api/v1/devices/enroll

Register a new device with the organization. This is typically called by the Zero agent.

Request

POST /api/v1/devices/enroll
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "device_name": "John's Laptop",
  "platform": "linux",
  "agent_version": "1.0.0",
  "enrollment_token": "enroll_abc123...",
  "hardware_id": "unique-hardware-identifier"
}

Response

HTTP/1.1 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "device_name": "John's Laptop",
  "platform": "linux",
  "status": "online",
  "vpn_config": {
    "endpoint": "vpn.zero.io:51820",
    "public_key": "server-public-key",
    "private_key": "device-private-key",
    "address": "10.100.0.15/24"
  },
  "policy": {
    "id": "policy-789",
    "name": "Default Security Policy"
  }
}

Update Device Status

PUT /api/v1/devices/:id/status

Update the status of a device (e.g., suspend or unsuspend).

PUT /api/v1/devices/550e8400-e29b-41d4-a716-446655440000/status
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "status": "suspended",
  "reason": "Security policy violation"
}

Response

{
  "status": "suspended",
  "updated_at": "2026-02-12T10:35:00Z"
}

Wipe Device

POST /api/v1/devices/:id/wipe

Initiate a remote wipe of the work profile on the device. This removes all work data and encryption keys.

Warning: This action is irreversible. All work profile data on the device will be permanently deleted. 
POST /api/v1/devices/550e8400-e29b-41d4-a716-446655440000/wipe
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "reason": "Employee offboarding",
  "notify_user": true
}

Response

{
  "message": "device wipe initiated",
  "wipe_id": "wipe_xyz789",
  "status": "pending",
  "initiated_at": "2026-02-12T10:40:00Z",
  "initiated_by": "admin@example.com"
}

GET /api/v1/devices/:id/wipe/:wipe_id

Check the status of a wipe operation.

{
  "wipe_id": "wipe_xyz789",
  "status": "completed",
  "initiated_at": "2026-02-12T10:40:00Z",
  "completed_at": "2026-02-12T10:41:30Z"
}

Delete Device

DELETE /api/v1/devices/:id

Remove a device from the organization. The device must be wiped first.

DELETE /api/v1/devices/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

HTTP/1.1 204 No Content

Device Policies

GET /api/v1/devices/:id/policy

Get the policy assigned to a device.

{
  "policy_id": "policy-789",
  "name": "Default Security Policy",
  "applied_at": "2026-02-01T09:00:00Z",
  "settings": {
    "screenshot_allowed": false,
    "clipboard_sharing": false,
    "usb_allowed": false
  }
}

PUT /api/v1/devices/:id/policy

Assign a different policy to a device.

PUT /api/v1/devices/550e8400-e29b-41d4-a716-446655440000/policy
Content-Type: application/json

{
  "policy_id": "policy-456"
}

Device Compliance

GET /api/v1/devices/:id/compliance

Get compliance status for a device.

{
  "status": "non_compliant",
  "last_check": "2026-02-12T10:00:00Z",
  "violations": [
    {
      "rule": "agent_version",
      "required": ">=1.0.0",
      "actual": "0.9.5",
      "severity": "high"
    },
    {
      "rule": "encryption_enabled",
      "required": true,
      "actual": true,
      "severity": "critical"
    }
  ]
}

Device Activity Logs

GET /api/v1/devices/:id/logs

Retrieve activity logs for a specific device.

{
  "data": [
    {
      "timestamp": "2026-02-12T10:30:00Z",
      "event": "device.checkin",
      "details": {"vpn_connected": true}
    },
    {
      "timestamp": "2026-02-12T09:00:00Z",
      "event": "policy.applied",
      "details": {"policy_id": "policy-789"}
    }
  ],
  "total": 150,
  "page": 1
}

Bulk Operations

POST /api/v1/devices/bulk

Perform operations on multiple devices at once.

POST /api/v1/devices/bulk
Content-Type: application/json

{
  "device_ids": ["device-1", "device-2", "device-3"],
  "action": "suspend",
  "reason": "Security audit"
}

Available Actions

  • suspend - Suspend devices
  • unsuspend - Unsuspend devices
  • wipe - Wipe all devices
  • assign_policy - Assign a policy to devices

Next Steps