quantumapi 0.1.0b0
Official Python SDK for QuantumAPI - Quantum-safe encryption and identity platform
Requires Python: >=3.9
Keywords: quantum, encryption, post-quantum, cryptography, security, api, sdk, ml-kem, ml-dsa, pqc

# QuantumAPI Python SDK

[![PyPI version](https://badge.fury.io/py/quantumapi.svg)](https://badge.fury.io/py/quantumapi)
[![Python Support](https://img.shields.io/pypi/pyversions/quantumapi)](https://pypi.org/project/quantumapi/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/quantumapi/quantumapi-python/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-quantumapi.eu-brightgreen)](https://docs.quantumapi.eu/sdk/python)

Official Python SDK for [QuantumAPI](https://quantumapi.eu) - The European quantum-safe encryption and identity platform.

## Features

- 🔐 **Quantum-Safe Encryption** - ML-KEM-768, ML-DSA-65, and hybrid encryption
- 🔑 **Key Management** - Generate, rotate, and manage cryptographic keys
- 🗄️ **Secret Vault** - Securely store and manage secrets with versioning
- 👤 **User Management** - Create and manage end-users with roles
- 🔍 **Audit Logs** - Query comprehensive audit trails
- 💳 **Billing Integration** - Access subscription and usage metrics
- 🚀 **Async/Await Support** - Full async support with httpx
- ⚡ **Automatic Retries** - Exponential backoff for transient failures
- 📊 **Rate Limiting** - Client-side rate limit tracking
- 🎯 **Type Safety** - Complete type hints with Pydantic models

## Installation

```bash
pip install quantumapi
```

For development:

```bash
pip install quantumapi[dev]
```

## Quick Start

```python
from quantumapi import QuantumAPIClient

# Initialize client with API key
client = QuantumAPIClient(api_key="qapi_xxx")

# Encrypt data
ciphertext = await client.encryption.encrypt(
    plaintext="secret data",
    key_id="550e8400-e29b-41d4-a716-446655440000"
)

# Store a secret
secret = await client.secrets.create(
    name="database_password",
    value="super_secret_password",
    labels=["production", "database"]
)

# Generate a new key pair
key = await client.keys.generate(
    name="encryption-key-2024",
    algorithm="ML-KEM-768",
    key_type="encryption"
)

# Retrieve secret
secret_value = await client.secrets.get(secret.id)
print(f"Secret: {secret_value.value}")
```

## Synchronous API

If you prefer synchronous code, use the `QuantumAPISyncClient`:

```python
from quantumapi import QuantumAPISyncClient

client = QuantumAPISyncClient(api_key="qapi_xxx")

# All methods work the same without await
ciphertext = client.encryption.encrypt(plaintext="secret data")
```

## Configuration

The SDK can be configured via environment variables or constructor arguments:

```python
client = QuantumAPIClient(
    api_key="qapi_xxx",              # Or set QUANTUMAPI_API_KEY
    base_url="https://api.quantumapi.eu",  # Optional, defaults to production
    timeout=30.0,                     # Request timeout in seconds
    max_retries=3,                    # Max retry attempts for failed requests
    enable_logging=True,              # Enable detailed logging
)
```

### Environment Variables

- `QUANTUMAPI_API_KEY` - Your API key
- `QUANTUMAPI_BASE_URL` - API base URL (default: https://api.quantumapi.eu)
- `QUANTUMAPI_TIMEOUT` - Request timeout in seconds (default: 30)
- `QUANTUMAPI_MAX_RETRIES` - Maximum retry attempts (default: 3)

## Core Modules

### Encryption Client

```python
# Encrypt data
result = await client.encryption.encrypt(
    plaintext="sensitive data",
    key_id="key-id",  # Optional, uses default key if not specified
    encoding="utf8"   # or "base64" for binary data
)

# Decrypt data
plaintext = await client.encryption.decrypt(
    encrypted_payload=result.encrypted_payload
)

# Sign data
signature = await client.encryption.sign(
    data="message to sign",
    key_id="signing-key-id"
)

# Verify signature
is_valid = await client.encryption.verify(
    data="message to sign",
    signature=signature.signature,
    key_id="signing-key-id"
)
```

### Keys Client

```python
# Generate key pair
key = await client.keys.generate(
    name="my-encryption-key",
    key_type="encryption",
    algorithm="ML-KEM-768",
    set_as_default=True
)

# List keys
keys = await client.keys.list(
    key_type="encryption",
    page=1,
    page_size=50
)

# Get key details
key = await client.keys.get(key_id="key-id")

# Rotate key
new_key = await client.keys.rotate(key_id="key-id")

# Delete key
await client.keys.delete(key_id="key-id")

# Set default key
await client.keys.set_default(key_id="key-id", key_type="encryption")
```

### Secrets Client

```python
# Create secret
secret = await client.secrets.create(
    name="api-key",
    value="secret_value",
    content_type="api-key",
    labels=["prod", "stripe"],
    expires_at="2025-12-31T23:59:59Z"
)

# List secrets
secrets = await client.secrets.list(
    content_type="password",
    label="production",
    page=1
)

# Get secret
secret = await client.secrets.get(secret_id="secret-id")

# Update secret value
await client.secrets.update_value(
    secret_id="secret-id",
    value="new_secret_value"
)

# Update secret metadata
await client.secrets.update(
    secret_id="secret-id",
    name="new-name",
    labels=["staging"]
)

# Delete secret
await client.secrets.delete(secret_id="secret-id")
```

### Users Client

```python
# Create user
user = await client.users.create(
    email="user@example.com",
    name="John Doe",
    role="developer"
)

# List users
users = await client.users.list(active_only=True)

# Update user
await client.users.update(
    user_id="user-id",
    name="Jane Doe",
    role="admin"
)

# Deactivate user
await client.users.deactivate(user_id="user-id")
```

### Applications Client

```python
# Create OIDC application
app = await client.applications.create(
    name="My App",
    redirect_uris=["https://myapp.com/callback"],
    scopes=["openid", "profile", "email"]
)

# List applications
apps = await client.applications.list()

# Update application
await client.applications.update(
    app_id="app-id",
    redirect_uris=["https://myapp.com/callback", "https://myapp.com/callback2"]
)
```

### Audit Client

```python
# Query audit logs
logs = await client.audit.list(
    action="secret_accessed",
    resource_type="Secret",
    start_date="2024-01-01",
    end_date="2024-12-31",
    page=1
)

# Export audit logs
csv_data = await client.audit.export(
    format="csv",
    start_date="2024-01-01",
    end_date="2024-12-31"
)
```

### Billing Client

```python
# Get subscription details
subscription = await client.billing.get_subscription()

# Get usage metrics
usage = await client.billing.get_usage(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

# List invoices
invoices = await client.billing.list_invoices()
```

### Health Client

```python
# Check API health
health = await client.health.check()
print(f"API Status: {health.status}")

# Get API version
version = await client.health.version()
print(f"API Version: {version.version}")

# Get rate limit status
rate_limit = await client.health.rate_limit()
print(f"Remaining: {rate_limit.remaining}/{rate_limit.limit}")
```

## Error Handling

The SDK provides typed exceptions for all error scenarios:

```python
from quantumapi import (
    QuantumAPIClient,
    AuthenticationError,
    PermissionError,
    NotFoundError,
    RateLimitError,
    ValidationError,
    ServerError,
    NetworkError,
)

try:
    secret = await client.secrets.get("invalid-id")
except NotFoundError as e:
    print(f"Secret not found: {e.message}")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except RateLimitError as e:
    print(f"Rate limit exceeded. Retry after {e.retry_after} seconds")
except ServerError as e:
    print(f"Server error: {e.message}")
except NetworkError as e:
    print(f"Network error: {e.message}")
```

## Pagination

List methods support automatic pagination:

```python
# Manual pagination
secrets = await client.secrets.list(page=1, page_size=100)

# Iterate through all pages
all_secrets = []
page = 1
while True:
    result = await client.secrets.list(page=page, page_size=100)
    all_secrets.extend(result.secrets)
    if not result.has_more:
        break
    page += 1
```

## Webhook Verification

Verify webhook signatures from QuantumAPI:

```python
from quantumapi.webhooks import verify_signature

# Verify webhook payload
is_valid = verify_signature(
    payload=request.body,
    signature=request.headers["X-QuantumAPI-Signature"],
    secret="your_webhook_secret"
)

if is_valid:
    # Process webhook event
    pass
```

## Logging

Enable detailed logging for debugging:

```python
import logging

logging.basicConfig(level=logging.DEBUG)

client = QuantumAPIClient(
    api_key="qapi_xxx",
    enable_logging=True
)
```

## Examples

Check out the [examples/](./examples/) directory for more comprehensive examples:

- [Basic encryption and decryption](./examples/01_encryption_basics.py)
- [Secret management](./examples/02_secret_management.py)
- [Key generation and rotation](./examples/03_key_management.py)
- [User management](./examples/04_user_management.py)
- [Audit log queries](./examples/05_audit_logs.py)
- [Django integration](./examples/frameworks/django_integration.py)
- [Flask integration](./examples/frameworks/flask_integration.py)

## Framework Integrations

### Django

```bash
pip install quantumapi[django]
```

```python
# settings.py
QUANTUMAPI = {
    'API_KEY': 'qapi_xxx',
    'BASE_URL': 'https://api.quantumapi.eu',
}

# Use in views
from quantumapi.integrations.django import get_client

async def my_view(request):
    client = get_client()
    secret = await client.secrets.get('secret-id')
    return JsonResponse({'value': secret.value})
```

### Flask

```bash
pip install quantumapi[flask]
```

```python
from flask import Flask
from quantumapi.integrations.flask import QuantumAPIFlask

app = Flask(__name__)
app.config['QUANTUMAPI_API_KEY'] = 'qapi_xxx'
qapi = QuantumAPIFlask(app)

@app.route('/secret/<secret_id>')
async def get_secret(secret_id):
    secret = await qapi.secrets.get(secret_id)
    return {'value': secret.value}
```

## Testing

Run tests:

```bash
pytest
```

Run tests with coverage:

```bash
pytest --cov=quantumapi --cov-report=html
```

## Development

```bash
# Clone repository
git clone https://github.com/quantumapi/quantumapi-python
cd quantumapi-python

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black quantumapi tests
isort quantumapi tests

# Type checking
mypy quantumapi

# Linting
flake8 quantumapi tests
```

## Requirements

- Python 3.9 or higher
- httpx >= 0.27.0
- pydantic >= 2.0.0
- python-dotenv >= 1.0.0
- cryptography >= 42.0.0

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://docs.quantumapi.eu/sdk/python)
- 💬 [Discord Community](https://discord.gg/quantumapi)
- 🐛 [Issue Tracker](https://github.com/quantumapi/quantumapi-python/issues)
- 📧 [Email Support](mailto:support@quantumapi.eu)

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this SDK.

## Security

For security concerns, please email security@quantumapi.eu. Do not create public issues for security vulnerabilities.

## Links

- [QuantumAPI Website](https://quantumapi.eu)
- [API Documentation](https://docs.quantumapi.eu)
- [Python SDK Documentation](https://docs.quantumapi.eu/sdk/python)
- [GitHub Repository](https://github.com/quantumapi/quantumapi-python)
- [PyPI Package](https://pypi.org/project/quantumapi/)