Machines

Machines represent individual devices activated under a license. Machine management uses license key authentication for activation, deactivation, and heartbeats, while listing and retrieval use API key authentication.

Activate Machine

POST/machines

Activate a machine for the authenticated license. Requires License Key auth.

Request Body

Parameter	Type	Required	Description
fingerprint	string	Required	Unique machine identifier (8-256 characters)
name	string	Optional	Human-readable machine name (max 255 chars)
platform	enum	Optional	Operating system: macos, windows, linux, docker, or kubernetes
hostname	string	Optional	Machine hostname (max 255 chars)
cores	integer	Optional	Number of CPU cores
metadata	object	Optional	Arbitrary key-value metadata

Example

curl -X POST https://your-instance.licentric.com/api/v1/machines \
  -H "Authorization: License DSK-A1B2-C3D4-E5F6-G7H8" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "hw-a1b2c3d4e5f6",
    "name": "Dev Laptop",
    "platform": "macos",
    "hostname": "macbook-pro.local",
    "cores": 8
  }'

201Machine activated

json

{
  "data": {
    "id": "f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82",
    "licenseId": "c8f4e9a2-3b71-4d5e-9f12-8a6b3c7d4e5f",
    "fingerprint": "hw-a1b2c3d4e5f6",
    "name": "Dev Laptop",
    "platform": "macos",
    "hostname": "macbook-pro.local",
    "cores": 8,
    "lastHeartbeatAt": "2026-03-01T14:00:00.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-03-01T14:00:00.000Z",
    "deletedAt": null,
    "metadata": {}
  }
}

List Machines

GET/machines

List machines with optional license filter. Requires API Key auth with machines:read scope.

Query Parameters

Parameter	Type	Required	Description
licenseId	uuid	Optional	Filter machines by license ID
cursor	uuid	Optional	Pagination cursor from previous response
limit	integer	Optional	Results per page (1-100, default 25)

Request

GET /api/v1/machines?licenseId=c8f4e9a2-3b71-4d5e-9f12-8a6b3c7d4e5f&limit=25

200Paginated list

json

{
  "data": [{
    "id": "f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82",
    "licenseId": "c8f4e9a2-3b71-4d5e-9f12-8a6b3c7d4e5f",
    "fingerprint": "hw-a1b2c3d4e5f6",
    "name": "Dev Laptop",
    "platform": "macos",
    "hostname": "macbook-pro.local",
    "cores": 8,
    "lastHeartbeatAt": "2026-03-01T14:00:00.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-03-01T14:00:00.000Z",
    "deletedAt": null,
    "metadata": {}
  }
  }],
  "pagination": { "nextCursor": "f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82", "hasMore": false }
}

Get Machine

GET/machines/:id

Retrieve a single machine by ID. Requires API Key auth with machines:read scope.

Request

GET /api/v1/machines/f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82

200Machine details

json

{
  "data": {
    "id": "f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82",
    "licenseId": "c8f4e9a2-3b71-4d5e-9f12-8a6b3c7d4e5f",
    "fingerprint": "hw-a1b2c3d4e5f6",
    "name": "Dev Laptop",
    "platform": "macos",
    "hostname": "macbook-pro.local",
    "cores": 8,
    "lastHeartbeatAt": "2026-03-01T14:00:00.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-03-01T14:00:00.000Z",
    "deletedAt": null,
    "metadata": {}
  }
}

Deactivate Machine

DELETE/machines/:id

Deactivate (soft-delete) a machine. Requires License Key auth. The authenticated license must own the machine.

Example

curl -X DELETE https://your-instance.licentric.com/api/v1/machines/f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82 \
  -H "Authorization: License DSK-A1B2-C3D4-E5F6-G7H8"

200Deactivated

json

{ "data": { "id": "f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82", "deleted": true } }

Heartbeat

POST/machines/:id/heartbeat

Send a heartbeat to keep a machine alive. Required when the license policy has requireHeartbeat enabled. Requires License Key auth.

Example

curl -X POST https://your-instance.licentric.com/api/v1/machines/f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82/heartbeat \
  -H "Authorization: License DSK-A1B2-C3D4-E5F6-G7H8"

200Heartbeat received

json

{
  "data": {
    "id": "f1a2b3c4-6e04-7081-c245-bd9e6f0a1b82",
    "lastHeartbeatAt": "2026-03-01T14:30:00.000Z"
  }
}

Heartbeat Cull Strategy

When a policy requires heartbeats, machines that miss their heartbeat window are marked as dead. The cull strategy determines whether dead machines are automatically deactivated (DEACTIVATE_DEAD) or kept for manual review (KEEP_DEAD).

Licenses Products