Activate Device

Last updated: Phase 8.5

Create a new activation for a license on a specific device/instance.

Endpoint

POST /api/v1/integration/activations

Headers

Header	Required	Value
X-API-Key	Yes	Your API key
Content-Type	Yes	application/json

Request Body

{
  "license_key": "VX-ACME-abc123def456",
  "instance_id": "server-prod-01",
  "device_fingerprint": "sha256-hash-of-device-info",
  "metadata": {
    "os": "linux",
    "version": "2.1.0"
  }
}

Field	Required	Type	Description
license_key	Yes	string	The license key
instance_id	Yes	string	Unique instance identifier
device_fingerprint	No	string	Device fingerprint hash (auto-generated from instance_id if omitted)
metadata	No	object	Additional metadata

Response (201 Created)

{
  "data": {
    "activation": {
      "id": 1,
      "license_key_id": 42,
      "instance_id": "server-prod-01",
      "device_fingerprint": "sha256-hash...",
      "status": "active",
      "activated_at": "2026-03-30T10:00:00.000000Z",
      "created_at": "2026-03-30T10:00:00.000000Z"
    }
  },
  "meta": {
    "request_id": "uuid",
    "api_version": "1"
  }
}

Idempotency

If an active activation already exists for the same license_key + instance_id, the existing activation is returned (no duplicate created). This makes the endpoint safe to retry.

Activation Limits

If the license has an activations.max entitlement, the limit is enforced:

{
  "error": {
    "code": "ACTIVATION.LIMIT_EXCEEDED",
    "message": "The maximum number of activations has been reached.",
    "status": 403,
    "type": "activation",
    "details": { "current": 5, "limit": 5 }
  },
  "meta": { "request_id": "uuid", "api_version": "1" }
}

Error Responses

Code	HTTP	Description
LICENSE.NOT_FOUND	404	License key not found
LICENSE.REVOKED	403	License revoked
ACTIVATION.INVALID	400	License not active
ACTIVATION.LIMIT_EXCEEDED	403	Max activations reached
AUTH.INVALID_API_KEY	401	Invalid API key