API Reference

Complete API documentation with examples, interactive testing, and detailed response schemas.

API Overview

Base URL

api.licensechain.app/v1

Authentication

All API requests require authentication using your API key.

Authorization Bearer your-api-key

Rate Limits

API requests are rate limited to ensure fair usage.

1000 requests per hour
100 requests per minute
Burst limit: 10 requests per second

API Endpoints

POST /v1/licenses/verify

Verify a license key (public endpoint, no authentication required).

Request body: key (required). Optional hwuid or hardwareId for hardware binding (ecosystem HMAC/HWUID contract). When the license has bound device(s), the provided hwuid must match one of them or the response is valid: false with reason: "hardware_id_mismatch". If no device is bound yet and hwuid is sent, the server performs first-use bind (records that device for future checks).

Verification Types: The response may include a verificationType field: basic (Free tier), advanced (Pro tier), or custom (Business/Enterprise tier with custom rules).

License assertion JWT (B2B): When the API has RS256 signing keys configured, successful responses may also include license_token, license_token_expires_at, and license_jwks_uri. Verify offline with GET /v1/licenses/jwks; require claim token_use = licensechain_license_v1. See Security guide.

Request:

{
  "key": "LC-XXXXXX-XXXXXX-XXXXXX",
  "hwuid": "optional-device-id"
}

Response (valid, typical):

{
  "valid": true,
  "status": "ACTIVE",
  "expiresAt": "2025-12-31T23:59:59Z",
  "email": "[email protected]",
  "verificationType": "advanced",
  "metadata": {
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "verifiedAt": "2024-01-01T00:00:00.000Z",
    "advancedChecks": true
  }
}

Response (valid, with license JWT when configured on API):

{
  "valid": true,
  "status": "ACTIVE",
  "expiresAt": "2025-12-31T23:59:59Z",
  "email": "[email protected]",
  "verificationType": "custom",
  "license_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImxpY2Vuc2VjaGFpbi0xIn0....signature",
  "license_token_expires_at": "2024-01-01T01:00:00.000Z",
  "license_jwks_uri": "https://api.licensechain.app/v1/licenses/jwks"
}

GET /v1/licenses/jwks

Public JWKS document for verifying license_token (RS256). Returns 503 if license JWT keys are not configured.

Example response:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "licensechain-1",
      "use": "sig",
      "alg": "RS256",
      "n": "base64url-modulus",
      "e": "AQAB"
    }
  ]
}

POST /v1/licenses/introspect

Authenticated introspection for license_token. Returns RFC 7662-style active with live license status checks (expiry/revocation/app scope). When a jti was revoked via POST /v1/licenses/revoke-token, returns active: false with reason: token_revoked.

Requires: Authentication (Bearer user JWT or app API key)

POST /v1/licenses/revoke-token

Revoke an issued license assertion JWT by denylisting its jti. Body: { "license_token": "...", "reason": "..." } (reason optional).

Requires: Authentication (same app/user ownership rules as license management)

GET /v1/licenses/:id

Get license details by ID or license key.

Requires: Authentication

Response:

{
  "id": "license_id",
  "appId": "app_id",
  "key": "LC-XXXXXX-XXXXXX-XXXXXX",
  "licenseKey": "LC-XXXXXX-XXXXXX-XXXXXX",
  "plan": "PRO",
  "status": "ACTIVE",
  "issuedTo": "John Doe",
  "issuedEmail": "[email protected]",
  "email": "[email protected]",
  "expiresAt": "2025-12-31T23:59:59Z",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

GET /v1/apps/:appId/licenses

List all licenses for an application.

Requires: Authentication

POST /v1/apps/:appId/licenses

Create a new license.

Requires: Authentication

Request:

{
  "appId": "app_id",
  "plan": "PRO",
  "issuedTo": "John Doe",
  "issuedEmail": "[email protected]",
  "expiresAt": "2025-12-31T23:59:59Z"
}

PATCH /v1/licenses/:id

Update a license.

Requires: Authentication

DELETE /v1/licenses/:id

Delete a license.

Requires: Authentication

GET /v1/apps

List all applications.

Requires: Authentication

POST /v1/apps

Create a new application.

Requires: Authentication

GET /v1/webhooks

List all webhooks.

Requires: Authentication

POST /v1/webhooks

Create a webhook.

Requires: Authentication

GET /v1/analytics/stats

Get analytics statistics.

Requires: Authentication

GET /v1/analytics/licenses

Get license analytics.

Requires: Authentication

View Complete API Reference