# LicenseKit

> LicenseKit is an AI-agent-friendly licensing and reporting API for software vendors. It handles product and policy setup, license issuance, activation, validation, metering, floating seats, offline issuance, device management, webhook delivery, and evidence-oriented reporting with frozen JSON, CSV, and PDF exports.

**Product:** `licensekit.dev`
**API Base:** `https://api.licensekit.dev`
**Current Posture:** Live free trial. The locked `v1 core` backend is complete and the reporting/export surface is implemented. The product is open for real-world usage and validation while broader operational evidence continues to grow.
**Positioning:** Commercial, API-first developer tool for teams shipping desktop, on-prem, edge, or installable software.

## Start Here

- **OpenAPI Spec:** [https://licensekit.dev/openapi.yaml](https://licensekit.dev/openapi.yaml)
- **Agent Quickstart:** [https://licensekit.dev/docs/agent-quickstart](https://licensekit.dev/docs/agent-quickstart)
- **API Contract Notes:** [https://licensekit.dev/docs/api-contract](https://licensekit.dev/docs/api-contract)
- **Full Agent Context:** [https://licensekit.dev/llms-full.txt](https://licensekit.dev/llms-full.txt)

## Product Shape

LicenseKit is backend-first. The API is the product center of gravity, and dashboards are replaceable clients of that API.

The current product story is:

1. a human or AI agent creates a product, policy, and scoped management key
2. licenses are issued and wired into an application through runtime validation
3. the backend enforces lifecycle state, entitlement rules, offline flows, metering, and floating leases
4. operators read reporting evidence and export frozen artifacts for usage, audit, customer, and settlement workflows

## Auth Model

Never mix these three auth surfaces:

- **Management:** `Authorization: Bearer <token>`
  Use for products, policies, customers, API keys, licenses, devices, events, webhooks, and reporting.
- **Runtime:** `Authorization: License <license-key>`
  Use for activation, validation, check, consume, deactivate, offline issuance, and floating leases.
- **System:** no auth
  Use for `/health`, `/healthz`, `/readyz`, `/metrics`, and `/api/v1/system/public-keys`.

## Response Model

- **Management success:** `{data, meta}`
- **Runtime success:** `{data, signature, meta}`

Runtime responses are Ed25519 signed. Signature verification is part of success handling, not optional diagnostics.

## Management Scopes

OpenAPI operations declare `x-required-scopes` for least-privilege automation.

Current management scopes:

- `admin`
- `product:read`
- `product:write`
- `license:read`
- `license:write`
- `device:write`
- `event:read`
- `ops:read`
- `report:read`
- `report:export`
- `webhook:write`

Common scope bundles:

- catalog setup: `product:write`
- license lifecycle: `license:write`
- device reset and blacklist: `device:write`
- raw event feed: `event:read`
- reporting reads: `report:read`
- frozen export creation and download: `report:export`

## What Exists Today

### Licensing

- products, policies, features, versions
- customers, licenses, orders, subscriptions
- license renewal, suspend, reinstate, revoke, transfer
- device list/get/reset/blacklist
- typed custom fields
- scoped management API keys with optional CIDR allow-lists
- runtime activation, validation, check, consume, deactivate
- offline issuance
- floating checkout, checkin, and heartbeat

### Security and Ops

- signed runtime responses with public key exposure
- signing-key rotation
- tamper-evident audit chain and verification
- durable webhook delivery with retries
- runtime and webhook operational summaries

### Reporting

- `GET /api/v1/activities`
- `GET /api/v1/reports/usage-summary`
- `GET /api/v1/reports/usage-ledger`
- `GET /api/v1/reports/license-audit`
- `GET /api/v1/reports/customer-summary`
- `GET /api/v1/reports/subscription-settlement`
- `POST /api/v1/reports/exports`
- `GET /api/v1/reports/exports/{id}`
- `GET /api/v1/reports/exports/{id}/download`

Reporting is built around an append-only activity ledger plus frozen export snapshots. JSON is the canonical snapshot format. CSV and PDF are deterministic render artifacts derived from that snapshot. PDF exports are rendered with Typst.

## AI Agent Rules

1. Use `operationId` and `x-required-scopes` from OpenAPI. Do not guess route names or scope bundles.
2. Use Bearer auth only for management routes and License auth only for runtime routes.
3. Verify runtime signatures against `/api/v1/system/public-keys`.
4. Treat orders and subscriptions as linked external record objects, not as a billing engine.
5. Treat reporting exports as frozen artifacts. Downloads should not be described as live reruns.
6. Describe the product as live and available for real-world trial usage, but do not overstate broad production validation that has not been demonstrated yet.

## Short Integration Path

1. create or load a scoped management key
2. create a product and policy
3. create a customer if needed
4. issue a license
5. wire runtime validate or check in the protected app
6. verify the signed runtime response
7. if metering or operator evidence matters, use the reporting endpoints and export surface

## SDKs

- TypeScript: `npm install @licensekit/sdk`
- Python: `pip install licensekit-sdk`
- Go: `go get github.com/drmain1/licensekit-go`
- Ruby: `gem install licensekit-ruby -v 0.1.0.alpha.1`
- .NET: `dotnet add package LicenseKit --prerelease`

For full agent context, including reporting semantics and export behavior, use [llms-full.txt](https://licensekit.dev/llms-full.txt).