QCOS Core Authentication

API Keys

Obtaining an API Key

1. Log in to the QCOS Portal
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Select permissions and expiration
5. Copy and securely store your key

⚠️ Security Warning: API keys are shown only once. Store them securely.

Key Types

Type	Prefix	Use Case
Live	qcos_live_	Production access
Test	qcos_test_	Sandbox/development
Restricted	qcos_rkey_	Limited permissions

---

Using API Keys

HTTP Header (Recommended)

curl -H "Authorization: Bearer qcos_live_abc123..." \
     https://api.softquantus.com/api/v2/backends

Python SDK

from qcos import Client

client = Client(api_key="qcos_live_abc123...")

Environment Variable

export QCOS_API_KEY="qcos_live_abc123..."

from qcos import Client

# Automatically reads from QCOS_API_KEY
client = Client()

---

Key Permissions

Scopes

Scope	Description
optimize:read	View optimization jobs
optimize:write	Submit optimization jobs
backends:read	List and view backends
evidence:read	View evidence bundles
evidence:write	Generate evidence
admin	Full account access

Creating Restricted Keys

# Create key with limited scope
POST /api/v2/keys
{
  "name": "production-optimizer",
  "scopes": ["optimize:read", "optimize:write", "backends:read"],
  "expires_in": "90d"
}

---

Key Rotation

Best Practices

1. Rotate regularly: Every 90 days for production keys
2. Use multiple keys: Different keys for different services
3. Monitor usage: Review API logs for anomalies
4. Revoke immediately: If key is compromised

Rotation Process

1. Create new key with same permissions
2. Update application configuration
3. Test new key in staging
4. Deploy to production
5. Revoke old key after grace period

# Revoke old key
DELETE /api/v2/keys/{key_id}

---

Enterprise Authentication

OAuth 2.0 / OIDC

For enterprise customers, QCOS supports OAuth 2.0 with OIDC:

# Authorization code flow
GET https://auth.softquantus.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  response_type=code&
  scope=optimize:read+optimize:write

SAML SSO

Enterprise plans include SAML SSO integration:

• Okta
• Azure AD
• Auth0
• Custom IdP

Contact enterprise@softquantus.com for setup.

Service Accounts

For machine-to-machine authentication:

{
  "grant_type": "client_credentials",
  "client_id": "service_abc123",
  "client_secret": "secret_xyz789"
}

---

Security Best Practices

DO ✅

• Store keys in environment variables or secret managers
• Use restricted scopes when possible
• Rotate keys regularly
• Use separate keys per environment
• Monitor key usage

DON'T ❌

• Commit keys to source control
• Share keys across team members
• Use live keys in development
• Use admin scope unless required
• Expose keys in client-side code

---

Rate Limits by Key Type

Key Type	Requests/min	Burst
Test	30	50
Live (Free)	60	100
Live (Pro)	300	500
Live (Enterprise)	Custom	Custom

Handling Rate Limits

from qcos import Client, RateLimitError

client = Client()

try:
    result = client.optimize(circuit)
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

---

Key Management API

List Keys

GET /api/v2/keys

{
  "data": {
    "keys": [
      {
        "id": "key_abc123",
        "name": "production-optimizer",
        "prefix": "qcos_live_abc...",
        "scopes": ["optimize:read", "optimize:write"],
        "created_at": "2026-01-01T00:00:00Z",
        "last_used_at": "2026-02-06T10:30:00Z",
        "expires_at": "2026-04-01T00:00:00Z"
      }
    ]
  }
}

Create Key

POST /api/v2/keys

{
  "name": "new-key",
  "scopes": ["optimize:read"],
  "expires_in": "30d"
}

Revoke Key

DELETE /api/v2/keys/{key_id}

---

Troubleshooting

Common Errors

Error	Cause	Solution
UNAUTHORIZED	Invalid key	Check key is correct
KEY_EXPIRED	Key expired	Create new key
INSUFFICIENT_SCOPE	Missing permission	Add required scope
KEY_REVOKED	Key was revoked	Create new key

Debugging Authentication

# Test your key
curl -v -H "Authorization: Bearer $QCOS_API_KEY" \
     https://api.softquantus.com/api/v2/me

# Response includes key info
{
  "data": {
    "key_id": "key_abc123",
    "scopes": ["optimize:read", "optimize:write"],
    "rate_limit": {
      "remaining": 295,
      "reset_at": "2026-02-06T12:01:00Z"
    }
  }
}

---

© 2024-2026 SoftQuantus Innovative OÜ