micro-license-server/README.md

Micro License Server

A very small, self-hosted license server intended for lower traffic projects.

This license server has no concept of separate devices, so use only if you don't intend to restrict the amount of devices that a license key can be used on.

Environment Setup

Replace the placeholder secrets in .env with secure random values using openssl rand:

sed -i \
  -e "s/PG_CHANGEME/$(openssl rand -base64 32)/" \
  -e "s/API_CHANGEME/$(openssl rand -base64 48)/" \
  .env

You can change NUM_KEY_CHUNKS to adjust how many chunks a license key consists of, and KEY_CHUNK_LENGTH to change how many characters appear in each chunk. This only changes how new keys are generated, so previous keys won't become invalidated.

API Endpoints

All authenticated endpoints expect a Bearer token via the Authorization header that matches API_KEY from .env. Unless stated otherwise, responses are JSON.

Method	Path	Auth	Description	Key Request Parameters	Response Highlights
GET	/	No	Returns server metadata.	–	{"version": "Micro License Server vX.Y.Z"}
POST	/license	Yes	Generates a new license key.	Query: is_active (bool, default true), expiration_date (ISO 8601, optional), info (string, optional metadata)	license_key, expiration_timestamp, is_active, info
GET	/is_valid	No	Validates a license key and records last usage time.	Query: license_key (required)	Boolean validity
POST	/license/{license_key}/disable	Yes	Deactivates a license key.	Path: license_key	license_key, is_active: false
POST	/license/{license_key}/enable	Yes	Reactivates a license key.	Path: license_key	license_key, is_active: true
POST	/license/{license_key}/expiration	Yes	Sets or clears a license key expiration.	Path: license_key; Query: expiration_date (ISO 8601 or omit to clear)	license_key, expiration_timestamp (nullable)
GET	/license/export	Yes	Exports license inventory as CSV ordered by issue time.	–	CSV with license_key,issue_timestamp,expiration_timestamp,is_active
GET	/history/export	Yes	Exports audit history as CSV.	Query: token (optional substring filter)	CSV with action,timestamp

Usage Examples

Set your API key once for convenience:

API_KEY=$(grep API_KEY .env | cut -d'"' -f2)
BASE_URL=http://127.0.0.1:8000

Create a license with optional metadata:

curl -X POST "$BASE_URL/license?info=QA+test+license" \
  -H "Authorization: Bearer $API_KEY"

Check whether a license key is valid:

curl "$BASE_URL/is_valid?license_key=PUT-LICENSE-HERE"

Disable and enable a license:

curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/disable" \
  -H "Authorization: Bearer $API_KEY"

curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/enable" \
  -H "Authorization: Bearer $API_KEY"

Update (or clear) the expiration timestamp:

curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/expiration" \
  -H "Authorization: Bearer $API_KEY" \
  -G --data-urlencode "expiration_date=$(date -u -Idate)T23:59:59Z"

curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/expiration" \
  -H "Authorization: Bearer $API_KEY"

Download the license inventory as CSV:

curl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/license/export" -o license_export.csv

Download history entries filtered by a token:

curl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/history/export?token=PUT-LICENSE-HERE" \
  -o history_export.csv