# LicenseKit

> LicenseKit is a licensing API for software vendors. It handles license creation, activation, validation, consumption metering, floating/concurrent seats, offline issuance, device management, and webhook delivery. The backend is PostgreSQL-backed with Ed25519 response signing. SDKs wrap the API so an AI coding agent can wire up licensing in minutes, not days.

- The canonical product name is `licensekit.dev`.
- Public beta launches on `April 5, 2026`.
- Hosted API base URL: `https://api.licensekit.dev`.
- Current launch posture: hosted API and first-party SDKs are being positioned as fully functional for public beta users at launch.
- The API contract is locked at `v1 core` — envelope shapes and endpoint behavior are stable for SDK generation.
- Management responses use `{data, meta}`. Runtime responses use `{data, signature, meta}`.
- Runtime responses are Ed25519-signed. Agents must wire signature verification as part of integration, not as optional.

## Getting Started

- [Agent Quickstart](https://licensekit.dev/docs/agent-quickstart): 5-step integration flow for humans and AI agents
- [OpenAPI Spec](https://licensekit.dev/openapi.yaml): Full machine-readable API contract (OpenAPI 3.1.0)
- [API Contract Notes](https://licensekit.dev/docs/api-contract): Compatibility-sensitive behavior for SDK consumers
- [Full Documentation](https://licensekit.dev/llms-full.txt): Complete inline documentation for large-context agents

## Public Beta Pricing

- `Sandbox` — Free
- 1 product
- up to 25 active licenses
- hosted API and public SDK access

- `Founding Beta` — `$49/month`
- up to 2,500 active licenses
- activation, validation, offline issuance, floating seats, webhooks, version checks
- 10,000 metered events per month included
- `+$10` per additional 10,000 metered events
- manual onboarding during public beta

- `Scale` — Contact
- custom limits, support, migration help, and higher-volume metered entitlement terms

## SDK — TypeScript

- Package: `@licensekit/sdk` on npm
- Install: `npm install @licensekit/sdk`
- Formats: ESM and CommonJS with full TypeScript definitions
- Auto-generated types from OpenAPI spec
- Least-privilege scope discovery via `x-required-scopes`
- Docs: `https://licensekit.dev/docs/agent-quickstart`
- API contract: `https://licensekit.dev/docs/api-contract`

```typescript
import { ManagementClient, RuntimeClient } from "@licensekit/sdk";

// Management: create products, licenses, customers (server-side)
const mgmt = new ManagementClient({
  baseUrl: "https://api.licensekit.dev",
  token: "lkm_your_management_token",
});

// Runtime: validate licenses in your app (client-side)
const runtime = new RuntimeClient({
  baseUrl: "https://api.licensekit.dev",
  licenseKey: "LK-XXXX-XXXX-XXXX",
});

const result = await runtime.validateLicense({
  body: { fingerprint: getDeviceId() }
});
if (result.data.valid) {
  console.log("License valid, features:", result.data.features);
}
```

## SDK — Python

- Package: `licensekit-sdk` on PyPI
- Install: `pip install --pre licensekit-sdk`
- Package page: `https://pypi.org/project/licensekit-sdk/`
- Current status: live prerelease package on PyPI
- Primary import: `from licensekit import ManagementClient, RuntimeClient, SystemClient`
- Docs: `https://licensekit.dev/docs/agent-quickstart`

## SDK — Go

- Module: `github.com/drmain1/licensekit-go`
- Install: `go get github.com/drmain1/licensekit-go`
- Source repo: `https://github.com/drmain1/licensekit-go`
- Current status: live public Go module tagged at `v0.1.1`
- Primary import shape: `licensekit.NewManagementClient(...)`
- Docs: `https://licensekit.dev/docs/agent-quickstart`

## SDK — Ruby

- Gem name: `licensekit-ruby`
- Package page: `https://rubygems.org/gems/licensekit-ruby`
- Source repo: `https://github.com/drmain1/licensekit-ruby`
- Current status: live prerelease gem on RubyGems at `0.1.0.alpha.1`
- Install: `gem install licensekit-ruby -v 0.1.0.alpha.1`
- Primary entrypoint: `LicenseKit::ManagementClient.new(...)`
- Docs: `https://licensekit.dev/docs/agent-quickstart`

## Auth Model

Two auth schemes, never mix them:

- **Management:** `Authorization: Bearer <token>` — for server-side automation (products, licenses, customers, webhooks)
- **Runtime:** `Authorization: License <license-key>` — for in-app license checks (activate, validate, check, consume, deactivate)
- **System:** No auth — health checks and public key retrieval

Management tokens are scoped. Every OpenAPI operation declares `x-required-scopes` for least-privilege key creation.

### Common Scope Bundles

- Catalog setup: `product:write`
- Catalog reads: `product:read`
- Customer and API key management: `admin`
- License lifecycle (create, renew, suspend, revoke, transfer): `license:write`
- License reads, device reads, feature reads: `license:read`
- Device reset and blacklist: `device:write`
- Event feed: `event:read`
- Webhook management: `webhook:write`

## API Reference — Management Endpoints

All management endpoints use `Authorization: Bearer <token>`.

### Products
- `GET /api/v1/products` — list products (product:read)
- `POST /api/v1/products` — create product (product:write)
- `GET /api/v1/products/{id}` — get product (product:read)
- `PATCH /api/v1/products/{id}` — update product (product:write)
- `DELETE /api/v1/products/{id}` — delete product (product:write)

### Versions
- `GET /api/v1/products/{id}/versions` — list versions (product:read)
- `POST /api/v1/products/{id}/versions` — create version (product:write)

### Policies
- `GET /api/v1/products/{id}/policies` — list policies (product:read)
- `POST /api/v1/products/{id}/policies` — create policy (product:write)
- `GET /api/v1/policies/{id}` — get policy (product:read)
- `PATCH /api/v1/policies/{id}` — update policy (product:write)
- `DELETE /api/v1/policies/{id}` — delete policy (product:write)

### Features
- `POST /api/v1/products/{id}/features` — create feature (product:write)
- `GET /api/v1/features/{id}` — get feature (product:read)

### Customers
- `GET /api/v1/customers` — list customers (admin)
- `POST /api/v1/customers` — create customer (admin)
- `GET /api/v1/customers/{id}` — get customer (admin)
- `PATCH /api/v1/customers/{id}` — update customer (admin)
- `DELETE /api/v1/customers/{id}` — delete customer (admin)

### Licenses
- `GET /api/v1/licenses` — list licenses (license:read)
- `POST /api/v1/licenses` — create license (license:write)
- `GET /api/v1/licenses/{id}` — get license (license:read)
- `POST /api/v1/licenses/{id}/renew` — renew license (license:write)
- `POST /api/v1/licenses/{id}/suspend` — suspend license (license:write)
- `POST /api/v1/licenses/{id}/reinstate` — reinstate license (license:write)
- `POST /api/v1/licenses/{id}/revoke` — revoke license (license:write)
- `POST /api/v1/licenses/{id}/transfer` — transfer license (license:write)
- `POST /api/v1/licenses/{id}/usage/reset` — reset consumption (license:write)

### License Features
- `GET /api/v1/licenses/{id}/features` — list assigned features (license:read)
- `POST /api/v1/licenses/{id}/features` — assign feature (license:write)
- `DELETE /api/v1/licenses/{id}/features` — remove feature (license:write)

### Devices
- `GET /api/v1/licenses/{id}/devices` — list devices (license:read)
- `GET /api/v1/licenses/{id}/devices/{device_id}` — get device (license:read)
- `POST /api/v1/licenses/{id}/devices/{device_id}/reset` — reset device (device:write)
- `POST /api/v1/licenses/{id}/devices/{device_id}/blacklist` — blacklist device (device:write)

### Custom Fields
- `GET /api/v1/products/{id}/custom-fields` — list field definitions (product:read)
- `POST /api/v1/products/{id}/custom-fields` — create field definition (product:write)
- `GET /api/v1/products/{id}/custom-fields/{field_id}` — get field definition (product:read)
- `PATCH /api/v1/products/{id}/custom-fields/{field_id}` — update field definition (product:write)
- `DELETE /api/v1/products/{id}/custom-fields/{field_id}` — delete field definition (product:write)
- `GET /api/v1/licenses/{id}/custom-fields/{field_id}` — get license field value (license:read)
- `PUT /api/v1/licenses/{id}/custom-fields/{field_id}` — set license field value (license:write)
- `GET /api/v1/customers/{id}/custom-fields/{field_id}` — get customer field value (admin)
- `PUT /api/v1/customers/{id}/custom-fields/{field_id}` — set customer field value (admin)

### Commerce
- `GET /api/v1/products/{id}/orders` — list orders (product:read)
- `POST /api/v1/products/{id}/orders` — create order (product:write)
- `GET /api/v1/orders/{id}` — get order (product:read)
- `PATCH /api/v1/orders/{id}` — update order (product:write)
- `GET /api/v1/products/{id}/subscriptions` — list subscriptions (product:read)
- `POST /api/v1/products/{id}/subscriptions` — create subscription (product:write)
- `GET /api/v1/subscriptions/{id}` — get subscription (product:read)
- `PATCH /api/v1/subscriptions/{id}` — update subscription (product:write)

### API Keys
- `GET /api/v1/api-keys` — list API keys (admin)
- `POST /api/v1/api-keys` — create scoped API key (admin)

### Events & Webhooks
- `GET /api/v1/events` — list events (event:read)
- `GET /api/v1/webhooks` — list webhooks (webhook:write)
- `POST /api/v1/webhooks` — create webhook (webhook:write)
- `GET /api/v1/webhooks/{id}` — get webhook (webhook:write)
- `PATCH /api/v1/webhooks/{id}` — update webhook (webhook:write)
- `DELETE /api/v1/webhooks/{id}` — delete webhook (webhook:write)

## API Reference — Runtime Endpoints

All runtime endpoints use `Authorization: License <license-key>`. Responses include `signature` for Ed25519 verification.

- `POST /api/v1/license/activate` — activate a license on a device
- `POST /api/v1/license/validate` — validate license status and entitlements
- `POST /api/v1/license/check` — lightweight license check
- `POST /api/v1/license/consume` — record metered consumption
- `POST /api/v1/license/deactivate` — deactivate a device
- `POST /api/v1/license/offline` — issue offline license (encrypted envelope)
- `POST /api/v1/license/floating/checkout` — check out a floating seat
- `POST /api/v1/license/floating/checkin` — release a floating seat
- `POST /api/v1/license/floating/heartbeat` — keep a floating seat alive

## API Reference — System Endpoints

No authentication required.

- `GET /health` — hosted-safe liveness probe for `api.licensekit.dev`
- `GET /healthz` — liveness probe
- `GET /readyz` — readiness probe (DB connected)
- `GET /metrics` — Prometheus metrics
- `GET /api/v1/system/public-keys` — Ed25519 public keys for signature verification

## Integration Rules for AI Agents

1. Use `operationId` and `x-required-scopes` from the OpenAPI spec — do not guess routes.
2. Create least-privilege API keys with `POST /api/v1/api-keys` before calling management endpoints.
3. Runtime calls use the license key, not the management token. Never embed management tokens in client code.
4. Verify Ed25519 signatures on all runtime responses. This is mandatory, not optional.
5. Supply `Idempotency-Key` on mutation endpoints that require it.
6. Expect additive fields over time. Do not break on unknown fields.
7. Orders and subscriptions are external record objects — they do not run a billing engine.
8. If the server returns `403 TOKEN_SCOPE_DENIED`, compare token scopes to that operation's `x-required-scopes`.

## Worked Example — Full Integration

### Step 1: Create a scoped management key

```bash
curl -X POST https://api.licensekit.dev/api/v1/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "catalog-setup", "scopes": ["product:write", "license:write"]}'
```

### Step 2: Create a product and policy

```bash
# Create product
curl -X POST https://api.licensekit.dev/api/v1/products \
  -H "Authorization: Bearer $SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App Pro", "code": "my-app-pro"}'

# Create policy (perpetual, 3 device limit)
curl -X POST https://api.licensekit.dev/api/v1/products/$PRODUCT_ID/policies \
  -H "Authorization: Bearer $SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pro License", "type": "perpetual", "max_devices": 3}'
```

### Step 3: Issue a license

```bash
curl -X POST https://api.licensekit.dev/api/v1/licenses \
  -H "Authorization: Bearer $SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "'$PRODUCT_ID'", "policy_id": "'$POLICY_ID'"}'
# Response includes the license key: "LK-XXXX-XXXX-XXXX"
```

### Step 4: Validate in your application

```typescript
import { RuntimeClient } from "@licensekit/sdk";

const client = new RuntimeClient({
  baseUrl: "https://api.licensekit.dev",
  licenseKey: process.env.LICENSE_KEY,
});

const { data, signature } = await client.validateLicense({
  body: { fingerprint: getMachineFingerprint() },
});

if (data.valid) {
  console.log("Licensed. Features:", data.features);
} else {
  console.log("License invalid:", data.detail);
  process.exit(1);
}
```

### Step 5: Verify public keys (optional local verification)

```bash
curl https://api.licensekit.dev/api/v1/system/public-keys
# Returns Ed25519 public keys for offline signature verification
```