Overview

Keylight is a thin, public HTTP API. The SDKs (Swift, Rust, JavaScript) wrap it, but you can call it directly from any platform that speaks HTTP.

Conventions

Base URL: https://api.keylight.dev
Scoping: every SDK endpoint is /{tenantId}/{productId}/{action}; the public keyset is /{tenantId}/.well-known/keylight-keys.
Auth: send your X-Keylight-SDK-Key header on every SDK endpoint (see SDK key). The keyset endpoint is public — no auth.
Format: requests and responses are JSON.
Lease: successful activate/validate responses include a signed Ed25519 v3 lease your app verifies offline (see Offline leases).

Common headers & path parameters

Every SDK endpoint (activate, validate, deactivate, free-tier, keyless) takes the same headers and path parameters:

Header	Required	Value
`Content-Type`	yes	`application/json`
`X-Keylight-SDK-Key`	yes (once the tenant has set one)	Your SDK key

Path parameter	Description
`tenantId`	Your tenant id
`productId`	The product id

The keyset endpoint is public — no X-Keylight-SDK-Key and no productId.

Lease format

Every activate/validate success includes a lease, Ed25519-signed by Keylight and verified offline by your app.

Field	Type	Meaning
`kid`	string	Key id in the tenant’s keyset
`licenseKeyHash`	hex string	SHA-256 of the normalized license key
`instanceId`	UUID	The activation this lease is bound to
`issuedAt`	unix seconds	When Keylight signed
`expiresAt`	unix seconds	`issuedAt` + 7 days
`status`	string	`"active"`, `"fallback"`, or `"expired"`
`entitlements`	string[]	Sorted feature strings granted (may be empty)
`signature`	base64	Ed25519 over `v3\|kid\|keyHash\|instanceId\|issuedAt\|expiresAt\|status\|entitlements_csv`

entitlements_csv is the entitlements array sorted and comma-joined (empty string when none), so client and server reconstruct an identical signed payload. Verification rules and the 7-day TTL: Ed25519 leases.

Rate limits and quotas

Monthly API calls — hard quota per plan; 429 + Retry-After once exceeded. Counters reset each calendar month.
Instance cap — hard per-plan cap on concurrent active instances; /activate returns 402 when exceeded.
License count — soft 100k ceiling per account; enforced at mint, not activation.

Plan quotas: Billing & plans.