Skip to main content

QuantumLock™ SDK Reference

Python SDK for Quantum Licensing Integration

The QuantumLock™ SDK provides complete integration for Python applications, including license generation, validation, management, revocation, and quantum cryptography.

Proprietary Software

The SDK is provided as a Python package protected with Nuitka (compiled to .so). Source code is not available.

Version 2.1.3

This documentation covers SDK version 2.1.3 with new license management methods: get_license(), revoke_license(), and get_revocations().


📦 Installation

The SDK is provided as a protected Python package.

Via SoftQuantus Portal

  1. Go to portal.softquantus.com
  2. Navigate to Downloads → SDK
  3. Download the package for your platform
  4. Install with pip:
pip install quantumlock_sdk-2.1.3-cp39-*.whl

Via pip (Authenticated)

pip install quantumlock-sdk --extra-index-url https://pypi.softquantus.com/simple

Requirements

  • Python 3.9+
  • Linux x86_64 or arm64, Windows, macOS
  • Dependencies: requests, cryptography

🚀 Quick Start

from quantumlock.sdk import QuantumLockClient

# Initialize client
client = QuantumLockClient(
api_key="your_api_key",
api_url="https://api.quantumlock.softquantus.com" # optional
)

# Generate license
license = client.generate_license(
end_customer_id="customer@company.com",
features=["premium", "api_access"],
valid_days=365
)

print(f"License: {license['license_key']}")
print(f"Quantum Fidelity: {license['qcos_fidelity']}")

# Validate license
result = client.validate_license(
license_key=license["license_key"],
end_customer_id="customer@company.com"
)

if result["valid"]:
print("✓ License is valid!")

📚 Classes

QuantumLockClient

Main client for interacting with the QuantumLock™ API.

from quantumlock.sdk import QuantumLockClient

client = QuantumLockClient(
api_key: str, # Your API Key (required)
api_url: str = "https://api.quantumlock.softquantus.com",
timeout: int = 30 # Timeout in seconds
)

Initialization Example:

import os
from quantumlock.sdk import QuantumLockClient

# From environment variable (recommended)
client = QuantumLockClient(
api_key=os.environ["QUANTUMLOCK_API_KEY"]
)

# With custom configuration
client = QuantumLockClient(
api_key="your_api_key",
api_url="https://api.quantumlock.softquantus.com",
timeout=60
)

📝 License Management Methods

generate_license()

Generates a new quantum license for your end-customer.

license = client.generate_license(
end_customer_id: str, # Unique ID of your customer (required)
features: List[str] = [], # Features to enable
valid_days: int = 365, # Validity in days
metadata: Dict = None # Custom metadata (optional)
)

Parameters:

ParameterTypeRequiredDescription
end_customer_idstrUnique customer identifier
featureslistList of feature strings
valid_daysintValidity period (default: 365)
metadatadictCustom key-value metadata

Returns:

{
"license_key": "QCOS-7A3F-9B2C-4E1D",
"quantum_signature": "a1b2c3d4...",
"end_customer_id": "customer@company.com",
"features": ["premium", "api_access"],
"valid_until": "2026-12-26T15:30:00Z",
"quantum_verified": True,
"qcos_fidelity": 0.9987,
"security_level": "QUANTUM_SECURED",
"generated_at": "2025-12-26T15:30:00Z"
}

Complete Example:

# Generate license with metadata
license = client.generate_license(
end_customer_id="user123@acme.com",
features=["premium", "analytics", "api_unlimited"],
valid_days=365,
metadata={
"company": "ACME Corp",
"department": "Engineering",
"plan": "enterprise"
}
)

# Save license to file
import json
with open("license.lic", "w") as f:
json.dump(license, f, indent=2)

print(f"✓ License generated: {license['license_key']}")
print(f" Expires: {license['valid_until']}")
print(f" Fidelity: {license['qcos_fidelity']:.4f}")

validate_license()

Validates an existing license against the API.

result = client.validate_license(
license_key: str, # License key (required)
end_customer_id: str # Customer ID (required)
)

Parameters:

ParameterTypeRequiredDescription
license_keystrThe license key to validate
end_customer_idstrCustomer identifier

Returns:

{
"valid": True,
"end_customer_id": "customer@company.com",
"quantum_verified": True,
"features": ["premium", "api_access"],
"expires_at": "2026-12-26T15:30:00Z",
"revoked": False,
"message": None
}

Example:

result = client.validate_license(
license_key="QCOS-7A3F-9B2C-4E1D",
end_customer_id="customer@company.com"
)

if result["valid"]:
print("✓ License valid!")
print(f" Features: {', '.join(result['features'])}")
print(f" Expires: {result['expires_at']}")
else:
print(f"✗ Invalid: {result['message']}")

list_licenses()

Lists all licenses generated by your account.

result = client.list_licenses(
skip: int = 0, # Records to skip (pagination)
limit: int = 100, # Maximum records to return
status: str = None # Filter by status
)

Parameters:

ParameterTypeRequiredDefaultDescription
skipint0Number of records to skip
limitint100Maximum records to return
statusstrNoneFilter: "active", "expired", "revoked"

Returns:

{
"total": 150,
"skip": 0,
"limit": 100,
"licenses": [
{
"license_key": "QCOS-7A3F-9B2C-4E1D",
"end_customer_id": "customer@company.com",
"features": ["premium", "api_access"],
"created_at": "2025-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z",
"status": "active",
"revoked": False
},
...
]
}

Examples:

# Get all licenses with pagination
all_licenses = []
skip = 0
limit = 100

while True:
result = client.list_licenses(skip=skip, limit=limit)
all_licenses.extend(result["licenses"])

if len(result["licenses"]) < limit:
break
skip += limit

print(f"Total licenses: {len(all_licenses)}")

# Get only active licenses
active = client.list_licenses(status="active")
print(f"Active licenses: {active['total']}")

# Get revoked licenses
revoked = client.list_licenses(status="revoked")
for lic in revoked["licenses"]:
print(f"Revoked: {lic['license_key']} - {lic.get('revoked_reason', 'N/A')}")

get_license()

Gets detailed information about a specific license. New in v2.1.3

license = client.get_license(
license_key: str # License key (required)
)

Parameters:

ParameterTypeRequiredDescription
license_keystrThe license key to retrieve

Returns:

{
"license_key": "QCOS-7A3F-9B2C-4E1D",
"end_customer_id": "customer@company.com",
"features": ["premium", "api_access"],
"created_at": "2025-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z",
"quantum_verified": True,
"qcos_fidelity": 0.9987,
"status": "active",
"revoked": False,
"revoked_at": None,
"revoked_reason": None,
"metadata": {
"company": "ACME Corp",
"plan": "enterprise"
},
"validation_count": 42,
"last_validated_at": "2025-06-15T14:20:00Z"
}

Example:

# Get license details
license = client.get_license("QCOS-7A3F-9B2C-4E1D")

print(f"License: {license['license_key']}")
print(f"Customer: {license['end_customer_id']}")
print(f"Status: {license['status']}")
print(f"Features: {', '.join(license['features'])}")
print(f"Validations: {license['validation_count']}")

if license['revoked']:
print(f"⚠️ REVOKED at {license['revoked_at']}")
print(f" Reason: {license['revoked_reason']}")

revoke_license()

Revokes an existing license. New in v2.1.3

result = client.revoke_license(
license_key: str, # License key (required)
reason: str = None # Revocation reason (optional)
)

Parameters:

ParameterTypeRequiredDescription
license_keystrThe license key to revoke
reasonstrHuman-readable reason

Returns:

{
"success": True,
"license_key": "QCOS-7A3F-9B2C-4E1D",
"revoked_at": "2025-06-15T14:30:00Z",
"reason": "Customer canceled subscription"
}

Example:

# Revoke a license
result = client.revoke_license(
license_key="QCOS-7A3F-9B2C-4E1D",
reason="Customer canceled subscription"
)

if result["success"]:
print(f"✓ License revoked: {result['license_key']}")
print(f" Revoked at: {result['revoked_at']}")
else:
print("✗ Failed to revoke license")

# Batch revocation
expired_licenses = client.list_licenses(status="expired")
for lic in expired_licenses["licenses"]:
client.revoke_license(
license_key=lic["license_key"],
reason="Automatic cleanup - expired license"
)
Irreversible Action

License revocation is permanent and cannot be undone. Revoked licenses will fail all future validations.


get_revocations()

Gets a list of revoked license IDs for local cache sync. New in v2.1.3

result = client.get_revocations(
since: str = None # ISO datetime to get revocations since (optional)
)

Parameters:

ParameterTypeRequiredDescription
sincestrISO 8601 datetime (e.g., "2025-01-01T00:00:00Z")

Returns:

{
"revoked_ids": [
"QCOS-7A3F-9B2C-4E1D",
"QCOS-8B4G-0C3D-5F2E",
"QCOS-9C5H-1D4E-6G3F"
],
"count": 3,
"as_of": "2025-06-15T14:30:00Z"
}

Example:

# Get all revocations
revocations = client.get_revocations()
print(f"Total revoked: {revocations['count']}")

# Sync local cache - only get new revocations
last_sync = "2025-06-01T00:00:00Z"
new_revocations = client.get_revocations(since=last_sync)

if new_revocations["count"] > 0:
print(f"New revocations since {last_sync}:")
for license_id in new_revocations["revoked_ids"]:
print(f" - {license_id}")
# Update local cache
local_cache.mark_revoked(license_id)

get_stats()

Returns account usage statistics.

stats = client.get_stats()

Returns:

{
"plan": "business",
"licenses_generated_month": 4523,
"licenses_remaining_month": 95477,
"max_licenses_month": 100000,
"revocations_this_month": 12,
"active_licenses": 4511
}

Example:

stats = client.get_stats()

print(f"Plan: {stats['plan']}")
print(f"Licenses this month: {stats['licenses_generated_month']}")
print(f"Remaining: {stats['licenses_remaining_month']}")
print(f"Active: {stats['active_licenses']}")

# Check if approaching limit
usage_pct = stats['licenses_generated_month'] / stats['max_licenses_month'] * 100
if usage_pct > 80:
print(f"⚠️ Warning: {usage_pct:.1f}% of monthly limit used!")

get_customer_info()

Returns account information.

info = client.get_customer_info()

Returns:

{
"id": "cust_abc123",
"name": "ACME Corp",
"email": "admin@acme.com",
"plan": "business",
"created_at": "2024-06-15T10:00:00Z"
}

⚛️ Quantum Cryptography Methods

The SDK offers end-to-end encryption using real quantum entropy.

quantum_encrypt()

Encrypts data with quantum keys.

result = client.quantum_encrypt(
data: bytes, # Data to encrypt
key_id: str = None, # Existing key ID (optional)
algorithm: str = "AES-256-GCM" # or "ChaCha20-Poly1305"
)

Returns:

{
"ciphertext": "encrypted_base64...",
"key_id": "key_quantum_abc123",
"iv": "iv_base64...",
"tag": "tag_base64...",
"algorithm": "AES-256-GCM",
"quantum_secured": True
}

Example:

# Encrypt sensitive data
secret_data = b"Confidential company data"

result = client.quantum_encrypt(secret_data)

# IMPORTANT: Save key_id to decrypt later!
print(f"Key ID: {result['key_id']}")
print(f"Ciphertext: {result['ciphertext'][:50]}...")

# Save result
import json
with open("encrypted.json", "w") as f:
json.dump(result, f)

quantum_decrypt()

Decrypts data encrypted with quantum keys.

plaintext = client.quantum_decrypt(
ciphertext: str, # Ciphertext in Base64
key_id: str, # Key ID used
iv: str, # IV in Base64
tag: str, # Authentication tag
algorithm: str = "AES-256-GCM"
)

Returns: bytes with decrypted data.

Example:

# Load encrypted data
import json
with open("encrypted.json") as f:
encrypted = json.load(f)

# Decrypt
plaintext = client.quantum_decrypt(
ciphertext=encrypted["ciphertext"],
key_id=encrypted["key_id"],
iv=encrypted["iv"],
tag=encrypted["tag"]
)

print(f"Data: {plaintext.decode()}")

quantum_sign()

Creates a digital signature with quantum security.

result = client.quantum_sign(
message: bytes, # Message to sign
key_id: str = None, # Existing key ID
algorithm: str = "SHA3-512-RSA" # or "Ed25519"
)

Returns:

{
"signature": "signature_base64...",
"key_id": "key_sign_abc123",
"public_key": "-----BEGIN PUBLIC KEY-----\n...",
"algorithm": "SHA3-512-RSA",
"quantum_nonce": "nonce_for_replay_protection"
}

quantum_verify()

Verifies a quantum digital signature.

result = client.quantum_verify(
message: bytes, # Original message
signature: str, # Signature in Base64
public_key: str, # PEM public key
algorithm: str = "SHA3-512-RSA"
)

Returns:

{
"valid": True,
"algorithm": "SHA3-512-RSA",
"verified_at": "2025-12-26T15:30:00Z"
}

quantum_key_exchange()

Establishes shared secret via quantum key exchange.

result = client.quantum_key_exchange(
peer_public_key: str = None, # Partner's key (optional)
key_bits: int = 256 # Key size (128-512)
)

Usage Protocol:

# === PARTY A (Alice) ===
# 1. Initiate exchange
exchange_a = client.quantum_key_exchange()
alice_public = exchange_a["public_key"]

# 2. Send alice_public to Bob (via secure channel)
send_to_bob(alice_public)

# === PARTY B (Bob) ===
# 3. Bob receives Alice's key and completes exchange
exchange_b = client.quantum_key_exchange(
peer_public_key=alice_public
)
bob_public = exchange_b["public_key"]
bob_secret = exchange_b["shared_secret"] # Bob has the secret!

# 4. Bob sends bob_public to Alice
send_to_alice(bob_public)

# === PARTY A (Alice) ===
# 5. Alice completes exchange with Bob's key
exchange_a2 = client.quantum_key_exchange(
peer_public_key=bob_public
)
alice_secret = exchange_a2["shared_secret"]

# alice_secret == bob_secret (same shared secret!)

quantum_entropy()

Gets pure quantum entropy.

result = client.quantum_entropy(
bits: int = 256, # Entropy bits (1-4096)
encoding: str = "hex" # "hex", "base64", or "raw"
)

Returns:

{
"entropy": "a7f3b2c1d4e5f6789...",
"bits": 256,
"source": "qcos_api",
"qubits": 16,
"fidelity": 0.9987,
"timestamp": "2025-12-26T15:30:00Z",
"job_id": "job_qcos_abc123"
}

quantum_health()

Checks quantum backend status.

health = client.quantum_health()

Returns:

{
"available": True,
"backends": ["qcos_api", "qiskit_local", "cryptographic"],
"qcos_api": {"available": True, "latency_ms": 45},
"qiskit_local": {"available": True}
}

🔐 LicenseValidator

License validator for offline use on the client.

from quantumlock.sdk import LicenseValidator

validator = LicenseValidator(
license_path: str = None, # License file path
online_validation: bool = False, # Enable online validation
api_url: str = "https://api.quantumlock.softquantus.com",
api_key: str = None # For online validation
)

validate()

Validates a license file.

is_valid = validator.validate(
license_path: str = None # Path (optional if already configured)
)

Example:

from quantumlock.sdk import LicenseValidator, LicenseError

validator = LicenseValidator()

try:
if validator.validate("/etc/myapp/license.lic"):
print("✓ License valid!")
info = validator.get_license_info()
print(f" Customer: {info['customer_id']}")
print(f" Expires: {info['valid_until']}")
else:
print("✗ License invalid or expired")
except LicenseError as e:
print(f"Error: {e}")

has_feature()

Checks if a feature is licensed.

if validator.has_feature("premium"):
enable_premium_features()

require_feature()

Decorator to protect functions.

from quantumlock.sdk import LicenseValidator, FeatureNotLicensed

validator = LicenseValidator(license_path="/etc/myapp/license.lic")
validator.validate()

@validator.require_feature("analytics")
def run_analytics():
"""Only executes if 'analytics' is in the license"""
return compute_analytics()

# Usage
try:
result = run_analytics()
except FeatureNotLicensed:
print("Feature 'analytics' is not licensed")

require_any_feature()

Decorator that requires at least one of the features.

@validator.require_any_feature(["basic", "premium", "enterprise"])
def some_feature():
return "Feature available"

get_license_info()

Returns information about the loaded license.

info = validator.get_license_info()

Returns:

{
"license_key": "QLOCK-7A3F-9B2C-4E1D",
"customer_id": "customer@company.com",
"features": ["premium", "api_access"],
"valid_until": "2026-12-26T15:30:00Z",
"quantum_verified": True
}

🚫 Exceptions

from quantumlock.sdk import LicenseError, FeatureNotLicensed

class LicenseError(Exception):
"""Base licensing error"""
pass

class FeatureNotLicensed(LicenseError):
"""Feature not included in license"""
pass

💡 Complete Examples

Desktop Application with Licensing

#!/usr/bin/env python3
"""Application with QuantumLock™ protection"""

import sys
from pathlib import Path
from quantumlock.sdk import LicenseValidator, LicenseError, FeatureNotLicensed

# Configure validator
LICENSE_FILE = Path.home() / ".myapp" / "license.lic"

validator = LicenseValidator(
license_path=str(LICENSE_FILE),
online_validation=True, # Validate online when possible
api_url="https://api.quantumlock.softquantus.com"
)

def check_license():
"""Verifies license at startup"""
if not LICENSE_FILE.exists():
print("❌ License not found!")
print(f" Place your license file at: {LICENSE_FILE}")
sys.exit(1)

try:
if not validator.validate():
print("❌ License invalid or expired!")
sys.exit(1)

info = validator.get_license_info()
print(f"✓ License valid for: {info['customer_id']}")
print(f" Features: {', '.join(info['features'])}")
print(f" Expires: {info['valid_until']}")

except LicenseError as e:
print(f"❌ License error: {e}")
sys.exit(1)

# Protected features
@validator.require_feature("basic")
def feature_basic():
return "Basic feature"

@validator.require_feature("premium")
def feature_premium():
return "Premium feature"

@validator.require_feature("enterprise")
def feature_enterprise():
return "Enterprise feature"

def main():
check_license()

# Use features
print(feature_basic())

try:
print(feature_premium())
except FeatureNotLicensed:
print("Premium not available on your plan")

if __name__ == "__main__":
main()

FastAPI Application with Licensing

from fastapi import FastAPI, Depends, HTTPException
from quantumlock.sdk import LicenseValidator, FeatureNotLicensed

app = FastAPI()

# Global validator
validator = LicenseValidator(license_path="/etc/myapi/license.lic")

@app.on_event("startup")
async def startup():
if not validator.validate():
raise RuntimeError("Invalid license!")

# Dependency to check features
def require_feature(feature: str):
def checker():
if not validator.has_feature(feature):
raise HTTPException(
status_code=403,
detail=f"Feature '{feature}' not licensed"
)
return Depends(checker)

# Protected endpoints
@app.get("/api/basic")
def basic_endpoint():
return {"tier": "basic"}

@app.get("/api/premium", dependencies=[require_feature("premium")])
def premium_endpoint():
return {"tier": "premium", "data": "exclusive"}

@app.get("/api/analytics", dependencies=[require_feature("analytics")])
def analytics_endpoint():
return {"analytics": "detailed data"}

License Management Dashboard

#!/usr/bin/env python3
"""License management script using new v2.1.3 methods"""

import os
from datetime import datetime
from quantumlock.sdk import QuantumLockClient

client = QuantumLockClient(api_key=os.environ["QUANTUMLOCK_API_KEY"])

def list_all_licenses():
"""List all licenses with status"""
result = client.list_licenses(limit=100)

print(f"\n📋 Licenses ({result['total']} total)")
print("-" * 80)

for lic in result["licenses"]:
status_icon = "✓" if lic["status"] == "active" else "✗"
print(f"{status_icon} {lic['license_key']} | {lic['end_customer_id']} | {lic['status']}")

def show_license_details(license_key: str):
"""Show detailed license information"""
license = client.get_license(license_key)

print(f"\n🔍 License Details: {license_key}")
print("-" * 40)
print(f"Customer: {license['end_customer_id']}")
print(f"Features: {', '.join(license['features'])}")
print(f"Created: {license['created_at']}")
print(f"Expires: {license['valid_until']}")
print(f"Status: {license['status']}")
print(f"Validations: {license['validation_count']}")

if license['revoked']:
print(f"\n⚠️ REVOKED: {license['revoked_at']}")
print(f" Reason: {license['revoked_reason']}")

def revoke_expired_licenses():
"""Revoke all expired licenses"""
expired = client.list_licenses(status="expired")

print(f"\n🗑️ Revoking {expired['total']} expired licenses...")

for lic in expired["licenses"]:
result = client.revoke_license(
license_key=lic["license_key"],
reason="Automatic cleanup - license expired"
)
print(f" ✓ Revoked: {lic['license_key']}")

def sync_revocation_cache():
"""Sync local revocation cache with server"""
# Get last sync time from local storage
last_sync = load_last_sync_time() # Your implementation

revocations = client.get_revocations(since=last_sync)

if revocations["count"] > 0:
print(f"📥 {revocations['count']} new revocations since {last_sync}")
for license_id in revocations["revoked_ids"]:
add_to_local_cache(license_id) # Your implementation

save_last_sync_time(revocations["as_of"]) # Your implementation

if __name__ == "__main__":
list_all_licenses()

SaaS Subscription Management

#!/usr/bin/env python3
"""SaaS license lifecycle management"""

from quantumlock.sdk import QuantumLockClient
import os

client = QuantumLockClient(api_key=os.environ["QUANTUMLOCK_API_KEY"])

def provision_customer(email: str, plan: str) -> dict:
"""Provision new customer with license"""
features_map = {
"starter": ["basic"],
"professional": ["basic", "premium", "api_access"],
"enterprise": ["basic", "premium", "api_access", "analytics", "unlimited"]
}

license = client.generate_license(
end_customer_id=email,
features=features_map.get(plan, ["basic"]),
valid_days=365,
metadata={"plan": plan, "provisioned": "auto"}
)

print(f"✓ Provisioned {plan} license for {email}")
return license

def upgrade_customer(license_key: str, new_plan: str) -> dict:
"""Upgrade customer plan (revoke old, create new)"""
# Get current license
old_license = client.get_license(license_key)

# Revoke old license
client.revoke_license(
license_key=license_key,
reason=f"Upgraded to {new_plan}"
)

# Create new license with upgraded features
return provision_customer(
email=old_license["end_customer_id"],
plan=new_plan
)

def cancel_subscription(license_key: str, reason: str = "Customer request"):
"""Cancel customer subscription"""
result = client.revoke_license(
license_key=license_key,
reason=reason
)
print(f"✓ Subscription canceled: {license_key}")
return result

🚫 Exceptions

from quantumlock.sdk import (
LicenseError,
FeatureNotLicensed,
LicenseExpired,
LicenseRevoked,
APIError
)

class LicenseError(Exception):
"""Base licensing error"""
pass

class FeatureNotLicensed(LicenseError):
"""Feature not included in license"""
pass

class LicenseExpired(LicenseError):
"""License has expired"""
pass

class LicenseRevoked(LicenseError):
"""License has been revoked"""
pass

class APIError(LicenseError):
"""API communication error"""
pass

Error Handling Example:

from quantumlock.sdk import (
QuantumLockClient,
LicenseError,
LicenseExpired,
LicenseRevoked,
APIError
)

client = QuantumLockClient(api_key="your_key")

try:
result = client.validate_license(
license_key="QCOS-XXXX-XXXX-XXXX",
end_customer_id="customer@example.com"
)
except LicenseRevoked as e:
print(f"License was revoked: {e}")
# Prompt user to purchase new license
except LicenseExpired as e:
print(f"License expired: {e}")
# Prompt user to renew
except APIError as e:
print(f"API error: {e}")
# Fall back to offline validation
except LicenseError as e:
print(f"License error: {e}")

📞 Support


© 2026 SoftQuantus innovative OÜ. All rights reserved.