Skip to main content

QuantumLock™ API Reference

Complete REST API Documentation​

Base URL: https://api.quantumlock.softquantus.com

🔑 Authentication​

All requests require authentication via API Key in the header:

X-API-Key: your_api_key_here

Get your API Key at the SoftQuantus Portal.

📋 Endpoints Overview​

Licenses​

MethodEndpointDescription
POST/api/v1/licenses/generateGenerate new license
POST/api/v1/licenses/validateValidate license
GET/api/v1/licensesList licenses

Customers​

MethodEndpointDescription
GET/api/v1/customers/meAccount information
GET/api/v1/customers/statsUsage statistics

Quantum​

MethodEndpointDescription
GET/api/v1/quantum/healthQuantum backend status
POST/api/v1/quantum/entropyGenerate quantum entropy
POST/api/v1/quantum/keysGenerate quantum key
POST/api/v1/quantum/rsaGenerate quantum RSA pair
POST/api/v1/quantum/crypto/encryptEncrypt with quantum key
POST/api/v1/quantum/crypto/decryptDecrypt
POST/api/v1/quantum/crypto/signDigital signature
POST/api/v1/quantum/crypto/verifyVerify signature
POST/api/v1/quantum/crypto/key-exchangeKey exchange

Health​

MethodEndpointDescription
GET/healthService health check

📝 Licenses​

POST /api/v1/licenses/generate​

Generates a new quantum license for your end-customer.

Request Body:

{
  "end_customer_id": "customer@company.com",
  "features": ["premium", "api_access"],
  "valid_days": 365,
  "metadata": {
    "company": "ACME Corp",
    "plan": "enterprise"
  }
}
FieldTypeRequiredDescription
end_customer_idstring✓Unique ID of your end customer
featuresstring[]List of features to enable
valid_daysintegerValidity in days (1-3650, default: 365)
metadataobjectCustom metadata

Response (201 Created):

{
  "license_key": "QLOCK-7A3F-9B2C-4E1D",
  "quantum_signature": "a1b2c3d4e5f6...128_chars...789xyz",
  "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"
}
FieldTypeDescription
license_keystringFormatted license key
quantum_signaturestringSHA3-512 quantum signature (128 hex chars)
end_customer_idstringEnd customer ID
featuresstring[]Enabled features
valid_untilstringExpiration date (ISO 8601)
quantum_verifiedbooleanUses real quantum entropy
qcos_fidelitynumberQuantum fidelity (0.0-1.0)
security_levelstringSecurity level
generated_atstringGeneration timestamp

Errors:

CodeDescription
401Invalid API Key
429Monthly limit reached
500Internal error

POST /api/v1/licenses/validate​

Validates an existing license.

Request Body:

{
  "license_key": "QLOCK-7A3F-9B2C-4E1D",
  "end_customer_id": "customer@company.com"
}

Response (200 OK - Valid):

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

Response (200 OK - Invalid):

{
  "valid": false,
  "end_customer_id": "customer@company.com",
  "quantum_verified": false,
  "features": null,
  "expires_at": null,
  "message": "License has expired."
}

GET /api/v1/licenses​

Lists all generated licenses.

Query Parameters:

ParameterTypeDefaultDescription
skipinteger0Records to skip
limitinteger100Maximum records

Response:

{
  "total": 150,
  "skip": 0,
  "limit": 100,
  "licenses": [
    {
      "license_key": "QLOCK-7A3F-9B2C-4E1D",
      "end_customer_id": "customer@company.com",
      "features": ["premium"],
      "valid_until": "2026-12-26T15:30:00Z",
      "created_at": "2025-12-26T15:30:00Z"
    }
  ]
}

👤 Customers​

GET /api/v1/customers/me​

Returns your account information.

Response:

{
  "id": "cust_abc123",
  "name": "ACME Corp",
  "email": "admin@acme.com",
  "plan": "business",
  "created_at": "2025-01-01T00:00:00Z"
}

GET /api/v1/customers/stats​

Returns usage statistics.

Response:

{
  "plan": "business",
  "licenses_generated_month": 4523,
  "licenses_remaining_month": 95477,
  "max_licenses_month": 100000,
  "total_licenses_all_time": 45230,
  "active_licenses": 38500
}

⚛️ Quantum API​

GET /api/v1/quantum/health​

Checks quantum backend status.

Response:

{
  "available": true,
  "backends": ["qcos_api", "qiskit_local", "cryptographic"],
  "qcos_api": {
    "available": true,
    "url": "https://api.softquantus.com",
    "latency_ms": 45
  },
  "qiskit_local": {
    "available": true,
    "simulator": "aer_simulator"
  },
  "test_result": {
    "bits": 64,
    "source": "qcos_api",
    "entropy": "a7f3b2c1d4e5..."
  }
}

POST /api/v1/quantum/entropy​

Generates true quantum entropy.

Request:

{
  "bits": 256,
  "encoding": "hex",
  "source": null
}
FieldTypeDefaultDescription
bitsinteger256Entropy bits (1-4096)
encodingstring"hex"Format: "hex", "base64", "raw"
sourcestringnullForce source: "qcos_api", "qiskit_local", "cryptographic"

Response:

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

POST /api/v1/quantum/crypto/encrypt​

Encrypts data with a quantum key.

Request:

{
  "plaintext": "SGVsbG8gV29ybGQh",
  "key_id": null,
  "algorithm": "AES-256-GCM"
}
FieldTypeDescription
plaintextstringData in Base64
key_idstringExisting key ID (optional)
algorithmstring"AES-256-GCM" or "ChaCha20-Poly1305"

Response:

{
  "ciphertext": "encrypted_base64...",
  "key_id": "key_quantum_abc123",
  "iv": "initialization_vector_base64",
  "tag": "auth_tag_base64",
  "algorithm": "AES-256-GCM",
  "quantum_secured": true
}

POST /api/v1/quantum/crypto/sign​

Creates a quantum digital signature.

Request:

{
  "message": "bWVzc2FnZSB0byBzaWdu",
  "key_id": null,
  "algorithm": "SHA3-512-RSA"
}

Response:

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

POST /api/v1/quantum/crypto/key-exchange​

Quantum key exchange protocol.

Flow:

  1. Party A calls without peer_public_key → receives public_key
  2. Party A sends public_key to Party B
  3. Party B calls with peer_public_key → receives shared_secret
  4. Party A calls with B's public key → same shared_secret

Request (initiate):

{
  "peer_public_key": null,
  "key_bits": 256
}

Response:

{
  "session_id": "session_abc123",
  "public_key": "public_key_base64...",
  "shared_secret": null
}

Request (complete):

{
  "peer_public_key": "peer_public_key_base64...",
  "key_bits": 256
}

Response:

{
  "session_id": "session_xyz789",
  "public_key": "my_public_key_base64...",
  "shared_secret": "shared_secret_base64..."
}

📊 Rate Limits​

PlanLicenses/MonthRequests/Min
Free10010
Startup10,000100
Business100,0001,000
EnterpriseUnlimited10,000

Rate limit headers returned:

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 95477
X-RateLimit-Reset: 1735689600

❌ Error Codes​

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API Key
403Forbidden - No permission for this resource
404Not Found - Resource not found
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable - Quantum backend unavailable

Error Format:

{
  "detail": "Monthly limit reached (100000 licenses).",
  "code": "RATE_LIMIT_EXCEEDED",
  "timestamp": "2025-12-26T15:30:00Z"
}

🔒 Security​

X-API-Key: your_api_key
Content-Type: application/json
Accept: application/json

Best Practices​

  1. Never expose your API Key in frontend code
  2. Use environment variables to store credentials
  3. Implement rate limiting in your backend
  4. Store licenses in a secure location on the client
  5. Use online validation when possible
  6. Implement caching to reduce API calls

📞 Support​

© 2025 SoftQuantus. All rights reserved.