TypeScript SDK

Use this page to integrate LicenseKit from a TypeScript or modern JavaScript application with the current first-party package.

Who This Is For

• Node.js and TypeScript developers integrating LicenseKit into an app or service
• AI agents generating TypeScript integration code
• teams that want typed clients plus verification helpers instead of calling the API by hand

When To Use This

Use this page when you are building with the @licensekit/sdk package.

Use it for management, runtime, system, reporting, and frozen export workflows from TypeScript or modern JavaScript.

How It Works

Install

npm install @licensekit/sdk

Current package facts from sdk/typescript/package.json:

• package name: @licensekit/sdk
• current version in this repo: 0.1.0-alpha.2
• Node requirement: >=20

Primary exports

The package exposes:

• ManagementClient
• RuntimeClient
• SystemClient
• PublicKeyStore
• verifyRuntimeResult
• getRequiredScopes
• hasRequiredScopes

Constructor shape

All clients take a baseUrl and optional transport settings:

{
  baseUrl: string;
  headers?: HeadersInit;
  timeoutMs?: number;
  userAgent?: string;
  retry?: { retries?: number; retryableMethods?: readonly string[] };
  fetch?: typeof fetch;
}

Client-specific auth fields:

• ManagementClient: token
• RuntimeClient: licenseKey
• SystemClient: no auth field

Auth split

• ManagementClient uses Authorization: Bearer <token>
• RuntimeClient uses Authorization: License <license-key>
• SystemClient uses no auth

Scope metadata

The package exports operation-to-scope helpers derived from its generated OpenAPI snapshot:

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

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

The same helpers should be used for reporting routes as well:

const exportScopes = getRequiredScopes("createReportExport");
const summaryAllowed = hasRequiredScopes("getUsageSummary", ["report:read"]);

Example

First successful runtime validation and verification:

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

const baseUrl = process.env.LICENSEKIT_BASE_URL ?? "https://api.licensekit.dev";
const licenseKey = process.env.LICENSEKIT_LICENSE_KEY!;

const runtime = new RuntimeClient({ baseUrl, licenseKey });
const system = new SystemClient({ baseUrl });

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

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

if (!verification.ok) {
  throw new Error(`signature verification failed for ${result.signature.kid}`);
}

console.log({
  licenseId: result.data.license_id,
  status: result.data.status,
  verified: verification.ok
});

For management setup:

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

const management = new ManagementClient({
  baseUrl: "https://api.licensekit.dev",
  token: process.env.LICENSEKIT_MANAGEMENT_TOKEN!
});

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

The package also exposes .raw companions when you need status codes or headers, which is especially useful for readiness probes.

Reporting example:

const summary = await management.getUsageSummary({
  query: {
    product_id: "prod_123",
    group_by: "customer_id"
  }
});

const exportJob = await management.createReportExport({
  body: {
    report_kind: "usage-summary",
    format: "csv",
    filters: {
      product_id: "prod_123"
    }
  }
});

Common Mistakes

• using token with RuntimeClient or licenseKey with ManagementClient
• treating the parsed runtime response as trusted before calling verifyRuntimeResult
• forgetting to normalize your own baseUrl when switching between hosted and self-hosted environments

Related Pages

• SDK Overview
• Reporting Overview
• Quickstart
• Auth And Scopes
• Runtime Verification