Activate

POST /{tenantId}/{productId}/activate

Registers a new device instance for a license key and returns a signed lease. Call this the first time a customer enters their key. Uses the common headers & path parameters.

Request body

Field	Type	Required	Description
`license_key`	string	yes	The raw key the customer pasted; normalized server-side
`instance_name`	string	yes	Human-readable device label shown in the dashboard
`free_tier_instance_id`	string	no	When converting from free tier, the prior anonymous instance id
`app_version`	string	no	Telemetry: your app version
`sdk_version`	string	no	Telemetry: the SDK version
`platform`	string	no	Telemetry: the platform

curl
JavaScript

curl -X POST https://api.keylight.dev/acme/notes/activate \
  -H "Content-Type: application/json" \
  -H "X-Keylight-SDK-Key: $KEYLIGHT_SDK_KEY" \
  -d '{
        "license_key": "ACME-XXXX-XXXX-XXXX-XXXX",
        "instance_name": "MacBook Pro"
      }'

import { Keylight } from "@keylight-dev/js";

const kl = new Keylight({
  tenantId: "acme",
  productId: "notes",
  sdkKey: process.env.KEYLIGHT_SDK_KEY,
});

const res = await kl.activate("ACME-XXXX-XXXX-XXXX-XXXX");
// res.activated, res.instanceId, res.lease

Response (200)

{
  "activated": true,
  "instance_id": "5f7e7b9a-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
  "license_expires_at": null,
  "lease": {
    "kid": "k1",
    "licenseKeyHash": "4e7a9c8b…",
    "instanceId": "5f7e7b9a-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
    "issuedAt": 1713546000,
    "expiresAt": 1714150800,
    "status": "active",
    "entitlements": ["pro"],
    "signature": "MEQCIB…"
  }
}

instance_id — Keylight-issued; store it and send it back on every validate/deactivate.
license_expires_at — unix seconds for a time-limited license, or null for perpetual.
Re-activating the same key from the same device returns the existing instance_id without consuming a new slot.

The lease object is detailed in Overview → Lease format.

Errors

Status	Condition
`400`	Invalid JSON body
`401`	Missing / invalid `X-Keylight-SDK-Key`
`402`	Plan instance limit reached
`403`	Tenant state or product does not allow activation
`404`	Tenant / product / license key not found
`422`	License revoked or expired; activation limit reached
`429`	Quota exceeded (`Retry-After` header)
`500`	Tenant not fully configured