License Server API Reference

A comprehensive license management API for software applications.

Features

• 🔐 Secure License Generation - Base58-encoded keys with 160-bit entropy
• 🛡️ Admin Protection - Admin endpoints require Bearer token authentication
• ⚡ Rate Limited - Different rate limits per endpoint category
• 🔍 License Validation - Real-time license verification and activation
• 📊 Usage Tracking - Monitor license usage and generate reports
• 🎯 Timing Attack Protection - Consistent response times prevent information leakage

API Workflow Diagrams

License Verification Flow

License Activation Flow

Admin License Management Flow

Authentication

Admin endpoints require a Bearer token in the Authorization header:

Authorization: Bearer your-admin-api-key

Rate Limits

• Validation Endpoints: 1000 req/15min (verify, validate, usage tracking)
• Activation Endpoints: 300 req/15min (activate, verify-file)
• Public Endpoints: 500 req/15min (export, list-activations)
• Management Endpoints: 100 req/15min (issue, revoke, delete)
• Admin-Info Endpoints: 50 req/15min (list-licenses, admin/stats, recent-activations)

Base URL

http://localhost:3000/v1

---

Health Endpoints

GET /

Health check endpoint to verify server status.

Response:

{
  "message": "License API is running",
  "version": "1.0.0"
}

---

License Validation

POST /v1/verify-license

Verify if a license key is valid.

Request Body:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28"
}

Response:

{
  "valid": true,
  "tier": "professional",
  "product_id": "my-product",
  "limits": {},
  "expires_at": "2024-12-31T23:59:59.000Z",
  "issued_to": "customer@example.com",
  "issued_at": "2024-01-01T00:00:00.000Z",
  "status": "active"
}

POST /v1/validate-license

Validate a license for a specific instance.

Request Body:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "instance_id": "unique-instance-id"
}

Response:

{
  "valid": true
}

---

License Activation

POST /v1/activate-license

Activate a license for a specific instance.

Request Body:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "instance_id": "unique-instance-id"
}

Response:

{
  "activated": true,
  "alreadyActivated": false
}

---

Usage Tracking

POST /v1/track-usage

Track usage for a license instance.

Request Body:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "metric": "api-calls",
  "increment": 1
}

Response:

{
  "ok": true,
  "metric": "api-calls",
  "usage": {
    "api-calls": 101
  }
}

POST /v1/usage-report

Get usage report for a license.

Request Body:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28"
}

Response:

{
  "valid": true,
  "status": "active",
  "expires_at": "2024-12-31T23:59:59.000Z",
  "metrics": [
    {
      "metric": "api-calls",
      "used": 101,
      "limit": 1000,
      "remaining": 899,
      "exceeded": false
    }
  ]
}

---

License Information

GET /v1/list-activations/:key

List all activations for a license.

Parameters:

• key (path) - The license key

Response:

{
  "license_key": "ABC123...",
  "activations": [
    {
      "instance_id": "unique-instance-id",
      "activated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET /v1/export-license/:key

Export a signed license object.

Parameters:

• key (path) - The license key

Response:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "tier": "professional",
  "product_id": "my-product",
  "issued_to": "customer@example.com",
  "expires_at": "2024-12-31T23:59:59.000Z",
  "limits": {},
  "sig": "3f2c9e1a7b5d8f0c1e4a6b9d2f5c8e0a1b3d5f7c9e1a3b5d7f9c1e3a5b7d9f1c"
}

---

Admin Endpoints

INFO

All admin endpoints require Bearer token authentication.

POST /v1/issue-license

Issue a new license.

Headers:

Authorization: Bearer your-admin-api-key

Request Body:

{
  "tier": "professional",
  "product_id": "my-product",
  "issued_to": "customer@example.com",
  "expires_at": "2024-12-31T23:59:59.000Z",
  "limits": {},
  "max_activations": 5
}

Response:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "status": "issued"
}

POST /v1/revoke-license

Revoke or reactivate a license.

Headers:

Authorization: Bearer your-admin-api-key

Request Body:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "revoked": true
}

Response:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "status": "revoked"
}

Setting revoked: false reactivates the license, returning status: "active". Returns 409 if the license is already in the requested state.

DELETE /v1/delete-license

Delete a license permanently.

Headers:

Authorization: Bearer your-admin-api-key

Request Body:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28"
}

Response:

{
  "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
  "deleted": true
}

GET /v1/list-licenses

List all licenses with optional filtering.

Headers:

Authorization: Bearer your-admin-api-key

Query Parameters:

• product_id (optional) - Filter by product ID
• status (optional) - Filter by status (active or revoked)
• limit (optional) - Maximum number of results (1-1000, default 50)
• offset (optional) - Pagination offset (default 0)

Response:

{
  "licenses": [
    {
      "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
      "tier": "professional",
      "product_id": "my-product",
      "issued_to": "customer@example.com",
      "expires_at": "2024-12-31T23:59:59.000Z",
      "status": "active",
      "max_activations": 5,
      "revoked_at": null
    }
  ],
  "total": 1
}

GET /v1/admin/stats

Get admin statistics.

Headers:

Authorization: Bearer your-admin-api-key

Response:

{
  "totalLicenses": 100,
  "activeLicenses": 95,
  "revokedLicenses": 5,
  "totalActivations": 250,
  "recentActivations": [
    {
      "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
      "instance_id": "unique-instance-id",
      "activated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET /v1/recent-activations

Get recent activations.

Headers:

Authorization: Bearer your-admin-api-key

Query Parameters:

• limit (optional) - Number of activations to return (default: 50)

Response:

[
  {
    "key": "7yChyZcfMG23Dx1sjBoLziPFrH4n-6f28",
    "instance_id": "unique-instance-id",
    "activated_at": "2024-01-01T00:00:00.000Z"
  }
]

---

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

403 Forbidden

{
  "error": "Unauthorized"
}

404 Not Found

{
  "error": "Not Found",
  "message": "License not found"
}

429 Too Many Requests

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}