New: Offline-first licensing with cryptographic validation. Learn more

Licenses API

The Licenses API allows you to create, manage, verify, and revoke software licenses. Licenses are cryptographically signed and can be validated offline by your application.

Endpoints Overview

Method Endpoint Description
POST /api/v1/licenses Create a new license
GET /api/v1/licenses List all licenses
GET /api/v1/licenses/:id Get license details
DELETE /api/v1/licenses/:id Revoke a license
GET /api/v1/licenses/:id/download Download license file
POST /api/v1/licenses/verify Verify a license
POST /api/v1/licenses/check-revocation Batch check revocation status
POST /api/v1/licenses/sync Report license usage

Create License

Generate a new license for a product. The license is cryptographically signed and returned as a base64-encoded blob.

Request

curl -X POST https://api.licenz.io/v1/licenses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "license_type": "subscription",
  "customer_id": "cust_12345",
  "customer_email": "customer@example.com",
  "features": ["pro", "analytics"],
  "valid_days": 365,
  "max_seats": 5,
  "hardware_binding": null
}'

Request Body

Field Type Required Description
product_id UUID Yes The product this license is for
license_type string No Type: perpetual, subscription, trial, node_locked, floating
customer_id string No Your internal customer identifier
customer_email string No Customer email address
features string[] No Features to enable (defaults to product defaults)
valid_days integer No Validity period in days (0 for perpetual)
max_seats integer No Maximum concurrent seats (default: 1)
hardware_binding object No Hardware fingerprint for node-locked licenses

Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "product_name": "My Application",
  "product_code": "myapp",
  "serial": "LIC-MYAPP-A1B2C3D4",
  "customer_id": "cust_12345",
  "customer_email": "customer@example.com",
  "status": "active",
  "valid_from": "2024-01-15T10:30:00Z",
  "valid_until": "2025-01-15T10:30:00Z",
  "features": ["pro", "analytics"],
  "max_seats": 5,
  "hardware_binding": null,
  "created_at": "2024-01-15T10:30:00Z",
  "revoked_at": null,
  "license_blob": "base64-encoded-license-file..."
}

License Blob

The license_blob field contains the cryptographically signed license file encoded in base64. Store this and provide it to your customers for offline validation.

List Licenses

Retrieve a paginated list of all licenses in your organization.

Request

curl https://api.licenz.io/v1/licenses \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter Type Description
product_id UUID Filter by product
status string Filter by status: active, revoked, expired, suspended
customer_email string Filter by customer email (partial match)
page integer Page number (1-based, default: 1)
per_page integer Items per page (default: 20, max: 100)

Response

{
  "licenses": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "product_id": "550e8400-e29b-41d4-a716-446655440000",
      "product_name": "My Application",
      "product_code": "myapp",
      "serial": "LIC-MYAPP-A1B2C3D4",
      "customer_id": "cust_12345",
      "customer_email": "customer@example.com",
      "status": "active",
      "valid_from": "2024-01-15T10:30:00Z",
      "valid_until": "2025-01-15T10:30:00Z",
      "features": ["pro", "analytics"],
      "max_seats": 5,
      "hardware_binding": null,
      "created_at": "2024-01-15T10:30:00Z",
      "revoked_at": null
    }
  ],
  "total": 1
}

Get License

Retrieve details of a specific license, including the license blob for download.

Request

curl https://api.licenz.io/v1/licenses/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "product_name": "My Application",
  "product_code": "myapp",
  "serial": "LIC-MYAPP-A1B2C3D4",
  "customer_id": "cust_12345",
  "customer_email": "customer@example.com",
  "status": "active",
  "valid_from": "2024-01-15T10:30:00Z",
  "valid_until": "2025-01-15T10:30:00Z",
  "features": ["pro", "analytics"],
  "max_seats": 5,
  "hardware_binding": null,
  "created_at": "2024-01-15T10:30:00Z",
  "revoked_at": null,
  "license_blob": "base64-encoded-license-file..."
}

Download License File

Download the license as a binary .lic file ready to distribute to customers.

Request

curl https://api.licenz.io/v1/licenses/7c9e6679-7425-40de-944b-e07fc1f90ae7/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o license.lic

Response

Returns the binary license file with the following headers:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="LIC-MYAPP-A1B2C3D4.lic"

Revoke License

Revoke a license, preventing it from being used. Revoked licenses will fail online verification checks.

Request

curl -X DELETE https://api.licenz.io/v1/licenses/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "message": "License revoked successfully"
}

Revocation is permanent

Once a license is revoked, it cannot be restored. For offline validation, revocation only takes effect when the client application syncs with the server.

Verify License

Verify a license's cryptographic signature and check its validity. This endpoint validates the license data and confirms it hasn't been tampered with.

Request

curl -X POST https://api.licenz.io/v1/licenses/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "license_blob": "base64-encoded-license-file...",
  "product_id": "550e8400-e29b-41d4-a716-446655440000"
}'

Request Body

Field Type Required Description
license_blob string Yes Base64-encoded license file content
product_id UUID Conditional Product ID (required if public_key not provided)
public_key string Conditional PEM-encoded public key (required if product_id not provided)

Response

{
  "valid": true,
  "license": {
    "serial": "LIC-MYAPP-A1B2C3D4",
    "product_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_id": "cust_12345",
    "features": ["pro", "analytics"],
    "valid_from": "2024-01-15T10:30:00Z",
    "valid_until": "2025-01-15T10:30:00Z",
    "is_expired": false
  },
  "errors": []
}

Check Revocation Status

Batch check the revocation status of multiple licenses. Useful for periodic sync from client applications.

Request

curl -X POST https://api.licenz.io/v1/licenses/check-revocation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "serials": [
    "LIC-MYAPP-A1B2C3D4",
    "LIC-MYAPP-E5F6G7H8"
  ]
}'

Request Body

Field Type Required Description
serials string[] Yes License serial numbers to check (max 100)

Response

{
  "results": [
    {
      "serial": "LIC-MYAPP-A1B2C3D4",
      "status": "active",
      "revoked_at": null
    },
    {
      "serial": "LIC-MYAPP-E5F6G7H8",
      "status": "revoked",
      "revoked_at": "2024-02-01T14:22:00Z"
    }
  ],
  "checked_at": "2024-03-15T09:00:00Z"
}

Status Values

Status Description
active License is valid and active
revoked License has been revoked
expired License has expired
suspended License is temporarily suspended
not_found Serial number not found

Sync Report

Report license usage from client applications. Used for analytics, seat tracking, and keeping licenses in sync.

Request

curl -X POST https://api.licenz.io/v1/licenses/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "license_serial": "LIC-MYAPP-A1B2C3D4",
  "hardware_fingerprint": "abc123def456",
  "app_version": "2.1.0",
  "features_used": ["pro"],
  "seats_in_use": 3
}'

Request Body

Field Type Required Description
license_serial string Yes The license serial number
hardware_fingerprint string No Machine hardware fingerprint
app_version string No Application version
features_used string[] No Features currently in use
seats_in_use integer No Current seat count

Response

{
  "status": "ok",
  "message": null,
  "server_time": "2024-03-15T09:00:00Z"
}

Status Values

Status Description
ok Sync successful, license is valid
revoked License has been revoked
expired License has expired
suspended License is suspended
not_found License not found

License Object

The license object contains all information about a license.

Field Type Description
id UUID Unique license identifier
product_id UUID Associated product ID
product_name string Product display name
product_code string Product code
serial string Human-readable serial number
customer_id string Customer identifier
customer_email string Customer email
status string License status
valid_from datetime Start of validity period
valid_until datetime End of validity period (null for perpetual)
features string[] Enabled feature flags
max_seats integer Maximum concurrent activations
hardware_binding object Hardware fingerprint for node-locked licenses
created_at datetime Creation timestamp
revoked_at datetime Revocation timestamp (if revoked)

Next Steps