Skip to main content

Authentication

QCOS uses API keys for authentication. This guide explains how to obtain and use your credentials.

Getting an API Key​

1. Create an Account​

Visit api.softquantus.com/signup to create your account.

2. Generate API Key​

After signing up, generate your API key from the dashboard or via CLI:

# Via CLI
qcos auth login
# Opens browser for authentication

qcos auth create-key --name "my-app-key"
# ✓ API Key created: qcos-xxxx-xxxx-xxxx
# ⚠ Store this key securely - it won't be shown again

3. Store Securely​

Store your API key using one of these methods:

export QCOS_API_KEY="qcos-xxxx-xxxx-xxxx"

Configuration File​

qcos configure
# Enter your API key when prompted
# Stored in ~/.qcos/config.json

.env File​

# .env (add to .gitignore!)
QCOS_API_KEY=qcos-xxxx-xxxx-xxxx

Using Your API Key​

Python SDK​

from qcos import QCOSClient

# Option 1: Environment variable (auto-detected)
client = QCOSClient()

# Option 2: Explicit parameter
client = QCOSClient(api_key="qcos-xxxx-xxxx-xxxx")

# Option 3: From file
client = QCOSClient.from_config("~/.qcos/config.json")

CLI​

# Option 1: Environment variable
export QCOS_API_KEY="qcos-xxxx-xxxx-xxxx"
qcos execute circuit.qasm

# Option 2: Flag
qcos execute circuit.qasm --api-key qcos-xxxx-xxxx-xxxx

# Option 3: Configured (saved with `qcos configure`)
qcos execute circuit.qasm

REST API​

# Option 1: X-API-Key header
curl -X POST https://api.softquantus.com/execute \
  -H "X-API-Key: qcos-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"qasm": "...", "shots": 1024}'

# Option 2: Bearer token
curl -X POST https://api.softquantus.com/execute \
  -H "Authorization: Bearer qcos-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"qasm": "...", "shots": 1024}'

API Key Tiers​

TierDaily LimitMax QubitsMax ShotsPriority
Free10 jobs2010,000Low
Pro100 jobs50100,000Normal
EnterpriseUnlimited1001,000,000High

Check Your Tier​

client = QCOSClient()
info = client.get_user_info()
print(f"Tier: {info.tier}")
print(f"Jobs today: {info.jobs_today}/{info.daily_limit}")
print(f"Max qubits: {info.max_qubits}")
# CLI
qcos user info

# Output:
# User: demo@example.com
# Tier: pro
# Jobs today: 23/100
# Max qubits: 50
# Max shots: 100,000
# REST API
curl https://api.softquantus.com/user/me \
  -H "X-API-Key: qcos-xxxx-xxxx-xxxx"

Managing API Keys​

List Keys​

qcos auth list-keys

# Output:
# ID              Name          Created      Last Used
# key_abc123      my-app-key    2024-01-15   2024-01-20
# key_def456      ci-cd-key     2024-01-18   2024-01-19

Revoke a Key​

qcos auth revoke-key key_abc123
# ✓ Key revoked successfully

Rotate Keys​

qcos auth rotate-key key_abc123
# ✓ New key: qcos-yyyy-yyyy-yyyy
# ⚠ Old key will be invalid in 24 hours

Security Best Practices​

✅ Do​

  • Store keys in environment variables or secure vaults
  • Use different keys for development and production
  • Rotate keys regularly (every 90 days)
  • Revoke unused keys immediately
  • Use the minimum required tier for each application

❌ Don't​

  • Commit keys to version control
  • Share keys between team members
  • Log or print keys in application output
  • Use production keys in development

Environment-Specific Configuration​

Development​

# dev_config.py
import os

QCOS_CONFIG = {
    "api_key": os.getenv("QCOS_DEV_API_KEY"),
    "api_url": "https://api.softquantus.com",
    "timeout": 60,
    "max_retries": 3,
}

Production​

# prod_config.py
import os

QCOS_CONFIG = {
    "api_key": os.getenv("QCOS_PROD_API_KEY"),
    "api_url": "https://api.softquantus.com",
    "timeout": 30,
    "max_retries": 5,
}

CI/CD​

# .github/workflows/test.yml
env:
  QCOS_API_KEY: ${{ secrets.QCOS_API_KEY }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run quantum tests
        run: |
          pip install qcos-sdk
          qcos execute tests/circuits/*.qasm

Troubleshooting​

Invalid API Key​

Error: Invalid API key. Please check your credentials.

Solution: Verify your key is correct and not expired.

Rate Limit Exceeded​

Error: Rate limit exceeded. Upgrade your tier or wait until tomorrow.

Solution: Upgrade to Pro/Enterprise or wait for daily reset (UTC midnight).

Quota Exceeded​

Error: Circuit exceeds your tier limits (25 qubits > 20 max).

Solution: Reduce circuit size or upgrade your tier.

Next Steps​