@licensekit/sdk

First-party TypeScript SDK for licensekit.dev.

It ships typed Management, Runtime, and System clients for the LicenseKit licensing API, including reporting and frozen export operations, plus scope metadata and Ed25519 runtime-signature verification helpers for activation, validation, metering, and offline-aware license flows.

Links:

• npm package: https://www.npmjs.com/package/@licensekit/sdk
• agent quickstart: https://licensekit.dev/docs/agent-quickstart
• API contract notes: https://licensekit.dev/docs/api-contract
• OpenAPI spec: https://licensekit.dev/openapi.yaml
• LLM reference: https://licensekit.dev/llms.txt

Primary hosted base URL used in examples:

• https://api.licensekit.dev

Local and self-hosted deployments remain first-class. Override baseUrl with your own origin, for example http://localhost:8080.

Install

npm install @licensekit/sdk

Quick Start

import {
  ManagementClient,
  PublicKeyStore,
  RuntimeClient,
  SystemClient,
  verifyRuntimeResult
} from "@licensekit/sdk";

const baseUrl = "https://api.licensekit.dev";

const system = new SystemClient({ baseUrl });
const health = await system.health();
console.log(health.data.status);

const management = new ManagementClient({
  baseUrl,
  token: process.env.LICENSEKIT_MANAGEMENT_TOKEN!
});

const product = await management.createProduct({
  body: {
    name: "Example App",
    code: "example-app"
  }
});

const runtime = new RuntimeClient({
  baseUrl,
  licenseKey: process.env.LICENSEKIT_LICENSE_KEY!
});

const result = await runtime.validateLicense({
  body: {
    fingerprint: "host-123"
  }
});

const publicKeys = await system.listPublicKeys();
const keyStore = new PublicKeyStore(publicKeys.data);
const verification = await verifyRuntimeResult(result, keyStore);

console.log(product.data.id, verification.ok);

Client Surfaces

• ManagementClient Uses Authorization: Bearer <token> for /api/v1/... management operations, including /api/v1/activities and /api/v1/reports/....
• RuntimeClient Uses Authorization: License <license-key> for /api/v1/license/... runtime operations.
• SystemClient Unauthenticated access to /health, /healthz, /readyz, /metrics, and /api/v1/system/public-keys.

Hosted docs and probes should prefer system.health() because GET /health is the Cloud Run-safe liveness path behind api.licensekit.dev. system.healthz() remains available for local and self-hosted compatibility.

Scope Metadata

Management least-privilege scopes are exported from the package and derived directly from the OpenAPI x-required-scopes metadata.

import { getRequiredScopes, hasRequiredScopes } from "@licensekit/sdk";

const scopes = getRequiredScopes("createProduct");
const allowed = hasRequiredScopes("createProduct", ["product:write"]);

Raw Response Access

Every client exposes a raw companion for callers that need HTTP status or headers.

import { SystemClient } from "@licensekit/sdk";

const system = new SystemClient({ baseUrl: "https://api.licensekit.dev" });
const ready = await system.raw.readyz();

console.log(ready.status, ready.data.data.status);

This is particularly useful for readiness checks, because GET /readyz may legitimately return 503 with a structured JSON body instead of an error envelope.

management.downloadReportExport() returns a Uint8Array so JSON, CSV, and PDF exports can all be handled without guessing the response shape up front. Inspect the Content-Type header from management.raw.downloadReportExport() when you need to branch on format.

Examples

Task-oriented examples live in examples/:

• 01-create-scoped-api-key.ts
• 02-create-product-and-policy.ts
• 03-create-customer-and-license.ts
• 04-runtime-validate-and-verify.ts
• 05-renew-license.ts
• 06-reset-device.ts

All examples default to https://api.licensekit.dev and can be redirected with LICENSEKIT_BASE_URL.

Development

Install dependencies:

npm install

Regenerate the SDK from the current OpenAPI:

npm run generate

Typecheck, test, and build:

npm run typecheck
npm test
npm run build

The generated transport and method wrappers are recreated from ../../api/openapi.yaml.