LicenseKit Docs

Appearance

Agent Quickstart ​

Use this page when a human or AI agent needs to integrate LicenseKit with minimal back-and-forth and without guessing the contract.

Who This Is For ​

  • AI coding agents making code changes in an application
  • developers preparing agent-readable integration context
  • backend teams automating catalog setup, issuance, and runtime verification

When To Use This ​

Use this page when the integrator is reading the API mechanically, not narratively.

This page assumes the agent can inspect api/openapi.yaml and should treat it as the contract source of truth.

How It Works ​

Canonical sources ​

When documents disagree, use this order:

  1. api/openapi.yaml
  2. docs/api_contract.md
  3. this page
  4. older or broader product docs

Client split ​

Never mix these surfaces:

  • Management client: /api/v1/... except public runtime and system routes
  • Runtime client: /api/v1/license/...
  • System client: /health, /healthz, /readyz, /metrics, /api/v1/system/public-keys

Auth split ​

  • Management: Authorization: Bearer <token>
  • Runtime: Authorization: License <license-key>
  • System: no auth

Scope rules ​

For management operations:

  • read x-required-scopes from the specific operation in api/openapi.yaml
  • treat that list as the minimum non-admin scope set
  • treat admin as a bootstrap or operator token, not the default day-to-day token
  • if the server returns 403 TOKEN_SCOPE_DENIED, compare the presented scopes to x-required-scopes

First-pass agent workflow ​

  1. inspect the target operation by operationId
  2. read its x-required-scopes
  3. create or load the narrowest practical management key
  4. create product, policy, and license records
  5. switch to the runtime client for in-app validation
  6. verify the runtime signature against published public keys

Rules that matter ​

  • runtime signature verification is part of success handling, not optional diagnostics
  • orders and subscriptions are linked external records, not a billing engine
  • reporting exports are frozen artifacts, not live reruns
  • hosted liveness checks should prefer /health

Example ​

The minimum reasoning pattern for an agent should look like this:

text
operationId: createLicense
auth surface: management
required scopes: ["license:write"]
success envelope: {data, meta}

Then the runtime path should switch cleanly:

text
operationId: validateLicense
auth surface: runtime
required auth: Authorization: License <license-key>
success envelope: {data, signature, meta}
follow-up: verify signature using GET /api/v1/system/public-keys

Common Mistakes ​

  • inferring scopes from route names instead of reading x-required-scopes
  • reusing a management token for runtime calls
  • flattening the response envelope and losing signature or meta
  • treating additive fields as breaking changes
  • assuming the dashboard is the product center of gravity instead of the API

Prototype docs shell for the rewrite workspace.

LicenseKit