Create License Artifact

Create a new license artifact with entitlements and optional device binding.

---

Endpoint

POST /api/v1/v2/artifacts

Request

Headers

Authorization: Bearer ql_your_api_key
Content-Type: application/json

Body

{
  "subject": "customer:acme-corp",
  "days_valid": 365,
  "grace_days": 14,
  "entitlements": [
    {
      "id": "feature:api",
      "type": "feature",
      "name": "API Access",
      "value": true
    },
    {
      "id": "seats:max",
      "type": "quantity",
      "name": "Maximum Seats",
      "value": 50
    }
  ],
  "binding": {
    "type": "hardware",
    "value": "sha256:abc123...",
    "algorithm": "SHA-256",
    "properties": ["cpu_id", "disk_serial", "mac_address"]
  },
  "metadata": {
    "product_name": "MyApp Enterprise",
    "product_version": "2.0",
    "customer_name": "ACME Corporation",
    "customer_email": "licenses@acme.com",
    "customer_id": "cust_12345",
    "order_id": "ord_98765",
    "notes": "Annual subscription",
    "tags": ["enterprise", "priority-support"]
  },
  "sign_pqc": true,
  "revocation_epoch": 0
}

Parameters

Parameter	Type	Required	Default	Description
subject	string	✅	-	Unique identifier for the licensee
days_valid	integer	❌	365	License validity in days (1-3650)
grace_days	integer	❌	7	Grace period after expiration (0-90)
entitlements	array	❌	[]	List of entitlements to grant
binding	object	❌	null	Device/hardware binding
metadata	object	❌	null	Additional license metadata
sign_pqc	boolean	❌	true	Include ML-DSA post-quantum signature
revocation_epoch	integer	❌	0	Minimum revocation epoch required

Entitlement Object

Field	Type	Required	Description
id	string	✅	Unique entitlement ID (e.g., feature:api)
type	string	❌	Type: feature, quantity, tier, module, quota
name	string	❌	Human-readable name
value	any	❌	Value (boolean, number, or string)
expires_at	datetime	❌	Per-entitlement expiration

Binding Object

Field	Type	Required	Description
type	string	❌	Binding type: hardware, user, domain, container
value	string	✅	Hash of the binding fingerprint
algorithm	string	❌	Hash algorithm used (default: SHA-256)
salt	string	❌	Salt used in fingerprint generation
properties	array	❌	List of properties used for fingerprint

---

Response

Success (200 OK)

{
  "artifact": {
    "header": {
      "typ": "QL-LICENSE",
      "ver": "1.0",
      "alg": "RSA-PSS-SHA256",
      "alg_pqc": "ML-DSA-65",
      "kid": "ql-api-v2-default"
    },
    "payload": {
      "jti": "b28a923a-c747-49b2-bc90-d87004c10379",
      "sub": "customer:acme-corp",
      "iss": "quantumlock.softquantus.com",
      "iat": 1735570068,
      "nbf": 1735570068,
      "exp": 1767106068,
      "grace_until": 1768315668,
      "revocation_epoch": 0,
      "entitlements": [
        {
          "id": "feature:api",
          "type": "feature",
          "name": "API Access",
          "value": true
        },
        {
          "id": "seats:max",
          "type": "quantity",
          "name": "Maximum Seats",
          "value": 50
        }
      ]
    },
    "signatures": {
      "classic": "base64-encoded-rsa-signature...",
      "pqc": "base64-encoded-mldsa-signature..."
    },
    "hash": "f83cd499e44c7f775712b59698896f5340731f5dfa376a9b782204c93f5928c"
  },
  "compact": "eyJ0eXAiOiAiUUwtTElDRU5TRSIsIC...",
  "hash": "f83cd499e44c7f775712b59698896f5340731f5dfa376a9b782204c93f5928c"
}

Response Fields

Field	Type	Description
artifact	object	Full license artifact with all fields
compact	string	Compact JWT-like representation for storage/transmission
hash	string	SHA-256 hash of the canonical artifact for verification

---

Examples

Minimal License

curl -X POST "https://quantumlock.softquantus.com/api/v1/v2/artifacts" \
  -H "Authorization: Bearer ql_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user@example.com"
  }'

Full Enterprise License

curl -X POST "https://quantumlock.softquantus.com/api/v1/v2/artifacts" \
  -H "Authorization: Bearer ql_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "customer:enterprise-001",
    "days_valid": 365,
    "grace_days": 30,
    "entitlements": [
      {"id": "tier:enterprise", "type": "tier", "value": "enterprise"},
      {"id": "feature:sso", "type": "feature", "value": true},
      {"id": "feature:audit", "type": "feature", "value": true},
      {"id": "seats:max", "type": "quantity", "value": 1000},
      {"id": "api:requests", "type": "quota", "value": 1000000}
    ],
    "metadata": {
      "product_name": "MyApp Enterprise",
      "customer_name": "Big Corp Inc",
      "customer_email": "admin@bigcorp.com",
      "tags": ["enterprise", "priority"]
    },
    "sign_pqc": true
  }'

Hardware-Bound License

curl -X POST "https://quantumlock.softquantus.com/api/v1/v2/artifacts" \
  -H "Authorization: Bearer ql_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "device:server-prod-01",
    "days_valid": 730,
    "binding": {
      "type": "hardware",
      "value": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "properties": ["cpu_id", "motherboard_serial"]
    },
    "entitlements": [
      {"id": "feature:all", "type": "feature", "value": true}
    ]
  }'

---

Error Responses

400 Bad Request

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "subject"],
      "msg": "Field required"
    }
  ]
}

401 Unauthorized

{
  "detail": "Invalid API key"
}

---

Notes

• The compact format is recommended for storage and transmission
• License IDs (jti) are UUIDs and globally unique
• Post-quantum signatures (sign_pqc: true) add ~2KB to the artifact size
• Hardware bindings are verified during validation