Skip to main content

QCOS Licensing System

Overview​

QCOS uses a centralized licensing system for code protection and access control:

  • Trial Licenses: 30-day evaluation (20 qubits max, kernel module only)
  • Paid Licenses: Full features, custom limits, perpetual or subscription
  • Online Validation: LUMI Worker validates with Portal Backend at startup
  • Audit Trail: License activations tracked in Portal Backend database

Architecture​

┌─────────────────┐         ┌──────────────────┐         ┌────────────────┐
│  LUMI Worker    │────────>│  Portal Backend  │────────>│   PostgreSQL   │
│                 │ Validate │                  │ Record  │                │
│ worker_local.py │<────────│ service_routes.py│<────────│ License tables │
└─────────────────┘  Result └──────────────────┘  Query  └────────────────┘
      ↑                              ↑
      │ QCOS_LICENSE_KEY             │ SERVICE_API_KEY
      │ SERVICE_API_KEY              │
      └──────────────────────────────┘

Getting Started​

1. Request Trial License​

curl -X POST https://portal-api.softquantus.com/public/trial/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "full_name": "Your Name",
    "company_name": "Your Company"
  }'

Response:

{
  "license_key": "softqcos-eval-abc123...",
  "valid_until": "2024-02-15T12:00:00Z",
  "next_steps": {
    "portal_login": "https://portal.softquantus.com",
    "download_qcos": "Contact support@softquantus.com",
    "documentation": "https://docs.softquantus.com"
  }
}

2. Configure LUMI Worker​

Copy .env.example to .env:

cd lumi_worker
cp .env.example .env

Edit .env:

# Required: Your trial license key
QCOS_LICENSE_KEY=softqcos-eval-abc123...

# Required: Service API key (contact support)
SERVICE_API_KEY=your-service-api-key-here

# Portal Backend URL (default: production)
PORTAL_URL=https://portal-api.softquantus.com

# Azure Storage (for queue processing)
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...

3. Run Worker​

python worker_local.py --max-jobs 10 --idle-timeout 600

Output:

==================================================
QCOS Azure Queue Worker (CPU) - License Validation
==================================================
🔐 Validating license: softqcos-eval-abc123...
✅ License valid!
   Type: evaluation
   Modules: kernel
   Expires: 2024-02-15T12:00:00Z
   Max qubits: 20
   Max concurrent jobs: 5
==================================================
QCOS Azure Queue Worker (CPU) Starting
Max jobs: 10
Idle timeout: 600s
==================================================

Trial License Limits​

FeatureTrialPaid
Duration30 daysCustom
Max Qubits20Unlimited
ModulesKernel onlyAll modules
Concurrent Jobs5Custom
SupportCommunityPriority

License Validation Flow​

Startup Validation​

  1. Worker reads QCOS_LICENSE_KEY from environment
  2. Calls POST /api/service/validate-license on Portal Backend
  3. Portal Backend checks:
    • License exists
    • Status is active
    • Not expired
  4. Records activation in LicenseActivation table (audit)
  5. Returns validation result + features
  6. Worker blocks execution if invalid

Authentication​

  • Service-to-Service: X-Service-Token header with SERVICE_API_KEY
  • User API: JWT token from Portal login

Portal Backend Configuration​

Environment Variables​

# portal-backend/.env
SERVICE_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/qcos_portal
JWT_SECRET=...
ADMIN_JWT_SECRET=...

Starting Portal Backend​

cd portal-backend
uvicorn app.main:app --host 0.0.0.0 --port 8000

API Endpoints​

Public Endpoints (No Auth)​

POST /public/trial/request​

Request 30-day trial license.

Request:

{
  "email": "user@company.com",
  "full_name": "John Doe",
  "company_name": "Acme Corp"
}

Response:

{
  "license_key": "softqcos-eval-...",
  "valid_until": "2024-02-15T12:00:00Z"
}

Service Endpoints (Service API Key)​

POST /api/service/validate-license​

Validate license for LUMI Worker.

Headers:

X-Service-Token: your-service-api-key

Request:

{
  "license_key": "softqcos-eval-...",
  "hostname": "lumi-worker-01",
  "environment": "production"
}

Response:

{
  "valid": true,
  "license_type": "evaluation",
  "modules": ["kernel"],
  "features": {
    "max_qubits": 20,
    "max_concurrent_jobs": 5
  },
  "expires_at": "2024-02-15T12:00:00Z"
}

Admin Endpoints (Admin JWT)​

See Portal Backend docs for admin endpoints:

  • /api/admin/licenses - Manage licenses
  • /api/admin/customers - Manage customers
  • /api/admin/contracts - Manage contracts

Upgrading from Trial to Paid​

  1. Login to Portal: https://portal.softquantus.com
  2. Navigate to "Licenses"
  3. Click "Upgrade" on trial license
  4. Complete payment
  5. Download new license key
  6. Update QCOS_LICENSE_KEY in .env
  7. Restart worker (no code changes needed)

Security​

Service API Key​

  • Length: Minimum 32 characters (automatically enforced)
  • Generation: Use secrets.token_urlsafe(32) in Python
  • Storage: Environment variable only (never commit to git)
  • Distribution: Share only with internal SoftQuantus services
  • Rotation: Rotate quarterly or if compromised

License Key​

  • Format: softqcos-{type}-{uuid}
  • Signature: RSA-4096 signed by License Authority
  • Verification: Offline (RSA) + Online (Portal Backend)
  • Binding: No machine binding (universal deployment)

Troubleshooting​

License Validation Failed​

Error: QCOS_LICENSE_KEY not set!

Solution: Set environment variable:

export QCOS_LICENSE_KEY=softqcos-eval-...

Error: SERVICE_API_KEY not set!

Solution: Contact SoftQuantus support for service API key.

Error: License not found

Solution: Verify license key is correct. Request new trial if expired.

Error: License expired

Solution:

Error: License validation timeout

Solution: Check network connectivity. Verify PORTAL_URL is accessible:

curl https://portal-api.softquantus.com/health

Offline Fallback (Future)​

Currently, LUMI Worker requires online validation. Future versions will support:

  • Offline Mode: Local RSA signature verification (90-day grace period)
  • License Cache: Cache valid licenses locally
  • Fallback: Use cached license if Portal Backend unreachable

Support​