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.
The SDK is provided as a Python package protected with Nuitka (compiled to .so). Source code is not available.
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
- Go to portal.softquantus.com
- Navigate to Downloads → SDK
- Download the package for your platform
- 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
end_customer_id | str | ✓ | Unique customer identifier |
features | list | List of feature strings | |
valid_days | int | Validity period (default: 365) | |
metadata | dict | Custom 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
license_key | str | ✓ | The license key to validate |
end_customer_id | str | ✓ | Customer 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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
skip | int | 0 | Number of records to skip | |
limit | int | 100 | Maximum records to return | |
status | str | None | Filter: "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:
| Parameter | Type | Required | Description |
|---|---|---|---|
license_key | str | ✓ | The 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
license_key | str | ✓ | The license key to revoke |
reason | str | Human-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"
)
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
since | str | ISO 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
- Email: support@softquantus.com
- Portal: portal.softquantus.com
- Docs: docs.softquantus.com
© 2026 SoftQuantus innovative OÜ. All rights reserved.