Keys

License keys are the core resource. Each key belongs to a product and tracks device activations.

Create a key

POST /v1/keys

Required permission: keys:write

{
  "product_id":       "prod_abc123",
  "plan":             "pro",
  "activation_limit": 3,
  "expires_at":       "2027-08-16T12:00:00Z",
  "metadata":         { "order_id": "ord_xyz" }
}

Field	Type	Required	Description
product_id	string	✅	Product this key belongs to
plan	string		Plan tier label (e.g. pro, enterprise)
activation_limit	integer		Max concurrent devices; default 3
expires_at	string		ISO 8601 expiry; omit for perpetual
metadata	object		Custom JSON — store order IDs, customer emails, etc.

The full key value is returned only at creation. Store it securely.

{
  "id":               "lic_def456",
  "key_value":        "MYAPP-ABCD-EFGH-IJKL",
  "plan":             "pro",
  "status":           "active",
  "activation_limit": 3,
  "expires_at":       "2027-08-16T12:00:00Z",
  "created_at":       "2026-08-16T12:00:00Z"
}

List keys

GET /v1/keys?product_id=&status=&page=0&page_size=20

Required permission: keys:read

Query parameters:

Param	Description
product_id	Filter by product
status	active | revoked | expired
plan	Filter by plan label
page	0-indexed page number
page_size	Results per page (max 100)

Get a key

GET /v1/keys/:id

Returns the key detail with its full activation history.

Revoke a key

POST /v1/keys/:id/revoke

Required permission: keys:revoke

{ "reason": "chargeback" }

Revocation is immediate. The KV cache is invalidated synchronously — subsequent validate calls return valid: false within milliseconds, globally.

Extend a key

POST /v1/keys/:id/extend

Required permission: keys:write

{ "expires_at": "2028-08-16T12:00:00Z" }

Extends the expiry date of an existing key. The KV cache is invalidated immediately.