License API

QuantumLock has two license formats:

v1 licenses — opaque license keys tracked server-side. Simple generate/validate/revoke.
v2 license artifacts — signed JSON documents (JWT-like structure: header, payload, signatures) that carry their own entitlements, validity window, grace period, device binding, and revocation epoch. Artifacts can be validated offline because the signature travels with the license.

v1 licenses

Generate

curl -X POST https://quantumlock.softquantus.com/api/v1/licenses/generate \
  -H "x-api-key: $QUANTUMLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_customer_id": "user@company.com",
    "features": ["premium", "api_access"],
    "valid_days": 365,
    "metadata": {"order": "SO-1042"}
  }'

Only end_customer_id is required. The response contains license_key, the feature list, valid_until, the signature, and provenance metadata for the key material (execution mode and, when a quantum entropy source was used, its evidence status). For batches, POST /api/v1/licenses/bulk accepts end_customer_ids (a list) with shared features and valid_days.

Validate

curl -X POST https://quantumlock.softquantus.com/api/v1/licenses/validate \
  -H "x-api-key: $QUANTUMLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "QLOCK-...", "end_customer_id": "user@company.com"}'

Both fields are required. The response reports valid, the features, and expiry.

Revoke

curl -X POST "https://quantumlock.softquantus.com/api/v1/licenses/QLOCK-.../revoke" \
  -H "x-api-key: $QUANTUMLOCK_API_KEY"

Requires the quantumlock:keys scope.

Hybrid validation (no API key)

POST /api/v1/licenses/validate/hybrid is deliberately unauthenticated: it exists so an application running on an end user’s machine can check revocation and expiry without embedding your API key. The license key itself is the credential.

curl -X POST https://quantumlock.softquantus.com/api/v1/licenses/validate/hybrid \
  -H "Content-Type: application/json" \
  -d '{
    "license_id": "QLOCK-...",
    "customer_id": "user@company.com",
    "signature": "..."
  }'

signature is optional; when present it is verified against the service signing keys.
The response carries a revoked flag read from the durable revocation record — the HybridLicenseValidator keys its persistent local revocation cache off this flag.
If the revocation record cannot be read, the endpoint answers 503 rather than defaulting to “not revoked”.
The response never discloses the issuing tenant: customer_id is echoed from the request, not read from the database, so the endpoint cannot be used to enumerate tenants.

v2 license artifacts

All artifact paths live under /api/v1/v2/ (the v2 router is mounted under the v1 prefix — use the paths exactly as written).

Create an artifact

curl -X POST https://quantumlock.softquantus.com/api/v1/v2/artifacts \
  -H "x-api-key: $QUANTUMLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "customer-42",
    "days_valid": 365,
    "grace_days": 7,
    "entitlements": [{"id": "premium", "name": "premium"}],
    "binding": {"machine_id": "5f2a..."},
    "sign_pqc": true
  }'

Request fields: subject (required), days_valid, grace_days, entitlements, binding, metadata, sign_pqc, revocation_epoch. The response returns the full artifact (header with kid/alg/alg_pqc, payload with jti/sub/iat/nbf/exp, and the signature block) plus a compact single-string form.

Validate an artifact

curl -X POST https://quantumlock.softquantus.com/api/v1/v2/validate \
  -H "x-api-key: $QUANTUMLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact_compact": "eyJ...",
    "device_fingerprint": {"machine_id": "5f2a..."}
  }'

Send either artifact_json or artifact_compact. Validation checks, in order: signatures, timestamps (nbf/exp/grace), device binding (when the artifact has one and a fingerprint is supplied), revocation, and the anti-rollback epoch.

Revocation and epochs

Operation	Call
Revoke	`POST /api/v1/v2/revoke` with `license_id` (the artifact `jti`), optional `reason`, `effective_until`, `notes`
Un-revoke	`DELETE /api/v1/v2/revoke/{license_id}`
Fetch revocation set	`GET /api/v1/v2/revocation`
Fetch revocation entries	`GET /api/v1/v2/revocations/list`

Revocation is epoch-based: every revocation advances a monotonically increasing epoch number. Clients persist the highest epoch they have seen; a revocation set with a lower epoch than the stored one is rejected as a rollback. This prevents an attacker from replaying an old (pre-revocation) revocation list at an offline client. Both revoke and un-revoke are tenant-scoped: you can only revoke licenses you issued.

Status proofs

curl -X POST https://quantumlock.softquantus.com/api/v1/v2/status-proof \
  -H "x-api-key: $QUANTUMLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"license_id": "jti-...", "ttl_hours": 24}'

A status proof is a signed, time-limited statement of a license’s current status (including its revocation epoch). Clients cache proofs and use them to answer validation while offline — see Activation & offline validation.

Verification keys

curl https://quantumlock.softquantus.com/api/v1/v2/keys \
  -H "x-api-key: $QUANTUMLOCK_API_KEY"

Returns the service’s public verification keys in a JWKS-like format so you can verify artifacts and status proofs yourself. Entries carry public_key material only for asymmetric keys (ML-DSA); each entry states whether offline_verification is possible. If the deployment holds no publishable public key, the endpoint answers 503 instead of returning keys that cannot verify anything.

Device binding, epoch, and grace at a glance

Mechanism	Where it lives	What it protects against
Device binding	`binding` on the artifact + `device_fingerprint` at validation	License reuse on other machines
Revocation epoch	Artifact payload + revocation set + client-side persisted epoch	Replay of stale revocation data (rollback)
Grace period	`grace_days` on the artifact	Hard failures at the exact expiry instant; validation reports `in_grace_period` so you can warn instead of block

Getting Started

Guides

Reference

Platform

v1 licenses

Generate

Validate

Revoke

Hybrid validation (no API key)

v2 license artifacts

Create an artifact

Validate an artifact

Revocation and epochs

Status proofs

Verification keys

Device binding, epoch, and grace at a glance

​v1 licenses

​Generate

​Validate

​Revoke

​Hybrid validation (no API key)

​v2 license artifacts

​Create an artifact

​Validate an artifact

​Revocation and epochs

​Status proofs

​Verification keys

​Device binding, epoch, and grace at a glance

v1 licenses

Generate

Validate

Revoke

Hybrid validation (no API key)

v2 license artifacts

Create an artifact

Validate an artifact

Revocation and epochs

Status proofs

Verification keys

Device binding, epoch, and grace at a glance