# LicenseKit — Full AI Agent Context

> LicenseKit is an AI-agent-friendly licensing and reporting API for software vendors. It combines licensing state enforcement, signed runtime validation, entitlement controls, external commerce linkage, and evidence-oriented reporting exports in one backend-first product.

**Product:** `licensekit.dev`
**API Base:** `https://api.licensekit.dev`
**CLI Binary:** `locksmith`
**Current Posture:** Live free trial. The locked `v1 core` backend and reporting export surface are implemented, and the product is open for real-world usage and validation while broader operational evidence continues to grow.

## Canonical Resources

- **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)
- **Docs Index:** [https://licensekit.dev/docs/](https://licensekit.dev/docs/)

When documents disagree, prefer:

1. `openapi.yaml`
2. API contract notes
3. agent quickstart
4. broader documentation and historical planning notes

## Product Direction

This is not an open-source-first dashboard product. It is a commercial, API-first developer tool.

The important direction is:

- backend-first
- automation-friendly
- AI-agent-readable
- useful for vendors shipping desktop, on-prem, edge, or installable software
- focused on licensing plus reporting, not on becoming a full billing platform

The API is the product center of gravity. Dashboards are replaceable clients of the API.

The intended workflow is:

1. a human or AI agent creates products, policies, and scoped management keys
2. licenses are issued and integrated into an application
3. runtime calls enforce state, entitlements, metering, version eligibility, and floating leases
4. operators use reporting APIs and frozen exports for usage visibility, audit evidence, and settlement support

## Current Platform Surface

### Management

The management API already includes:

- products
- policies
- customers
- API keys
- licenses
- features
- custom fields
- versions
- devices
- events
- webhooks
- orders
- subscriptions
- reporting reads and exports

### Runtime

The runtime API already includes:

- activation
- validation
- periodic check
- metered consume
- deactivation
- offline issuance
- floating checkout
- floating checkin
- floating heartbeat

### Security and Operator Features

The backend also includes:

- Ed25519-signed runtime responses
- public verification key exposure at `/api/v1/system/public-keys`
- signing-key rotation
- hashed storage for management API keys
- hashed storage for license keys
- route-scoped management auth with optional CIDR restrictions
- tamper-evident audit chain
- audit-chain verification via CLI
- durable webhook delivery with retries
- runtime and webhook operational summaries

## Auth Model

There are three auth surfaces. Never mix them.

### 1. Management

- Header: `Authorization: Bearer <token>`
- Success envelope: `{data, meta}`
- Use for: catalog setup, license management, customer records, reporting, events, webhooks

### 2. Runtime

- Header: `Authorization: License <license-key>`
- Success envelope: `{data, signature, meta}`
- Use for: in-app validation and enforcement

### 3. System

- No auth
- Use for:
  - `/health`
  - `/healthz`
  - `/readyz`
  - `/metrics`
  - `/api/v1/system/public-keys`

Hosted deployments should prefer `/health` for liveness. Local and self-hosted compatibility still includes `/healthz`.

## Scope Model

Every management operation publishes `x-required-scopes` in OpenAPI so AI agents and SDKs can choose least-privilege keys.

Current management scopes:

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

Recommended mental model:

- `admin` is for bootstrap or operator-level workflows
- narrower scopes should be used for normal automation
- if a route returns `403 TOKEN_SCOPE_DENIED`, compare the token scopes to the route’s `x-required-scopes`

Useful scope bundles:

- catalog setup and maintenance: `product:write`
- catalog readback: `product:read`
- license issuance and lifecycle: `license:write`
- license reads and device reads: `license:read`
- device reset and blacklist: `device:write`
- raw event feed polling: `event:read`
- ops rollups: `ops:read`
- reporting reads: `report:read`
- reporting exports: `report:export`
- webhook endpoint management: `webhook:write`

## Response Contracts

### Management Responses

- success: `{data, meta}`
- error: `{error, meta}`

### Runtime Responses

- success: `{data, signature, meta}`
- signature covers the JSON bytes of `data`
- runtime signature verification is mandatory

### Compatibility Notes

Integrations should assume:

- additive fields may appear over time
- envelope shapes should remain stable
- undocumented side effects should not be relied on

## Licensing Semantics That Matter

### Orders and Subscriptions

Orders and subscriptions are first-class linked records, but they are not a billing engine.

Use them for:

- external commerce linkage
- origin attribution on licenses
- operator visibility
- reporting filters and settlement evidence

Do not assume:

- provider-specific proration
- invoicing logic
- automatic pricing semantics

### Renewal

Renewal and extension are implemented.

Important behavior:

- only renewable license types can be renewed
- renewals are idempotent per license and `Idempotency-Key`
- order and subscription references can be validated on renewal
- renewal metadata can reference commerce records without rewriting stored origin linkage

### Devices

Device management is implemented.

Operators can:

- list devices for a license
- fetch a device
- reset a device
- blacklist a device

### Version Eligibility

Runtime version checks are implemented.

Important behavior:

- app-version gating only matters once a product has a version catalog
- if no catalog exists, gating is not enforced
- once a catalog exists, unknown versions are rejected
- eligibility is based on maintenance or expiry windows depending on license type

## Reporting Direction

Reporting is now part of the shipped product story, not just an ops add-on.

The reporting center of gravity is:

- visibility
- controls
- evidence

The target operator is a vendor who needs more than basic health counters. They need usage evidence, license audit context, customer summaries, and settlement-oriented exports.

LicenseKit reporting is still not a pricing engine. It is an evidence and export layer built on top of licensing activity.

## Reporting Data Model

Reporting is built around an append-only activity ledger.

The ledger captures normalized, point-in-time attribution such as:

- action
- source
- product
- customer
- license
- order
- subscription
- feature code
- amount
- status code
- result class
- reason code
- device
- app version
- request id
- metadata

This matters because current-state commerce and license tables are mutable, but reporting artifacts need frozen attribution.

## Reporting Read APIs

Current reporting read endpoints:

- `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`

### 1. Activities

Use `GET /api/v1/activities` for a normalized activity feed across runtime and management evidence.

This is the best first reporting endpoint when an agent needs recent evidence without assembling it from several resource lists.

### 2. Usage Summary

Use `GET /api/v1/reports/usage-summary` for grouped usage totals over a time window.

Typical grouping dimensions include:

- time
- product
- customer
- license
- order
- subscription
- feature
- source
- result class

### 3. Usage Ledger

Use `GET /api/v1/reports/usage-ledger` for row-level usage evidence.

This is the reporting surface that best matches:

- metered evidence review
- dispute resolution
- downstream BI ingestion

### 4. License Audit

Use `GET /api/v1/reports/license-audit` for a license-centric packet that combines:

- license record
- usage totals
- runtime summary
- devices
- activity rows
- audit events
- linked order or subscription when present

### 5. Customer Summary

Use `GET /api/v1/reports/customer-summary` for a customer-centric view that combines:

- customer record
- usage totals
- runtime summary
- counts
- grouped usage
- licenses
- orders
- subscriptions

### 6. Subscription Settlement

Use `GET /api/v1/reports/subscription-settlement` for usage-ledger-based settlement evidence tied to a subscription or order.

This is not a pricing engine. It is the usage evidence layer that pricing can sit on top of externally.

## Reporting Exports

Frozen report exports are implemented.

Export endpoints:

- `POST /api/v1/reports/exports`
- `GET /api/v1/reports/exports/{id}`
- `GET /api/v1/reports/exports/{id}/download`

Required scope:

- `report:export`

### Export Rule

Exports are generated from frozen JSON snapshots, not from live reruns during download.

That is a core product rule.

### Supported Export Formats

- `json`
- `csv`
- `pdf`

### Format Semantics

- **JSON** is the canonical frozen snapshot
- **CSV** is a deterministic projection from that frozen snapshot
- **PDF** is a deterministic render artifact derived from that frozen snapshot

PDF exports are rendered with Typst. They should be described as render artifacts, not as the system of record.

### Export Metadata

Export metadata includes:

- export id
- report kind
- format
- status
- filters
- snapshot digest
- artifact digest
- content type
- creator
- timestamps
- download URL

### What Agents Should Assume

When dealing with exports:

- download should return the exact stored artifact
- download must not rerun the report
- JSON is the best source for machine post-processing
- CSV is for tabular export workflows
- PDF is for human-readable statements and packets

## Reporting Limits To Keep Visible

Even with reporting implemented, the current product still has intentional boundaries:

- reporting is not a billing engine
- settlement is usage-evidence-oriented, not price-engine-oriented
- some runtime evidence is still stronger in ops or audit surfaces than in first-class reporting rows
- broader operational validation still needs more staging and soak evidence

## Webhooks and Events

### Events

Use `GET /api/v1/events` for the raw audit/event feed.

This is different from reporting:

- events are raw mutation history
- reporting is normalized evidence and summary access

### Webhooks

Webhook endpoint management is implemented, and delivery is durable with retries.

What exists today:

- endpoint create, list, get, update, delete
- sealed secrets
- signed outbound deliveries
- durable retries
- ops webhook health rollups

What does not define the product yet:

- webhook history as a full reporting substitute
- a public replay-management surface matching dedicated webhook event products

## Runtime Rules For Agents

An AI agent integrating LicenseKit should follow these rules:

1. Use OpenAPI `operationId` plus `x-required-scopes`. Do not infer behavior from naming guesses.
2. Separate management, runtime, and system clients immediately.
3. Never use a management token for runtime routes.
4. Always verify runtime signatures against `/api/v1/system/public-keys`.
5. Treat runtime verification as part of success handling.
6. Use `Idempotency-Key` where required on mutation-heavy routes.
7. Treat orders and subscriptions as linked record objects, not as billing automation.
8. Use reporting APIs when you need evidence, not just current-state resource lists.
9. Treat export downloads as frozen artifacts.
10. 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.

## Recommended First-Pass Workflow

For a normal implementation, the shortest path is:

1. create or load an `admin` token only long enough to bootstrap narrower keys
2. create a scoped management key for the specific job
3. create a product and policy
4. create a customer if needed
5. create a license
6. integrate runtime `validate` or `check`
7. verify runtime signatures
8. if metering or operator visibility matters, assign features and use `consume`
9. if reporting matters, start with `usage-summary`, `usage-ledger`, or `license-audit`
10. if a frozen artifact is needed, create a report export in `json`, `csv`, or `pdf`

## SDKs

Current SDK packages:

- 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`

SDKs should preserve the same conceptual split:

- `ManagementClient`
- `RuntimeClient`
- `SystemClient`
- crypto or verification helpers

## Deployment

LicenseKit can be self-hosted with PostgreSQL and the `locksmith` binary.

Typical local/self-hosted flow:

```bash
./bin/locksmith init
./bin/locksmith migrate up
./bin/locksmith serve
```

Core expectations:

- PostgreSQL is the source of truth
- the API layer is stateless
- signing keys are required
- runtime response verification depends on the published public key surface

## Status Language To Reuse

Use language close to this:

> LicenseKit is live and available through a free trial. The locked `v1 core` backend is complete, the reporting export surface is implemented, and the platform is being validated through real-world integrations and usage.

Avoid language like:

- production proven at broad scale
- battle-tested public launch
- fully validated across unrestricted production workloads

unless new evidence exists and the broader documentation is updated to match.