Two Modes

apikee operates in one of two modes. You start in local mode and can add server mode by setting two config values — no code changes required.

Local mode

Local mode is the default. It requires nothing beyond a signing secret.

What it does:

• Creates HMAC-SHA256 signed keys with embedded claims
• Validates keys entirely in-process — no network, no database
• Provides middleware for every supported framework
• Auto-injects Swagger/OpenAPI security schemes

What it doesn't do:

• Track usage per key
• Detect fraud or abuse
• Enforce rate limits
• Manage clients and subscriptions

When to use it:

• Development and testing
• Internal microservices
• Apps where you own both ends
• When you want zero external dependencies at runtime

# Local mode — nothing else needed
apikee = Apikee(secrets=["your-secret"])

Server mode

Server mode connects your app to the apikee developer platform via an encrypted channel.

What it adds:

• Usage tracking per key and endpoint
• Server-side fraud detection (velocity checks, IP reputation)
• IP whitelisting per client
• Rate limiting via configurable templates (per hour / day / week / month)
• Client management — create, update, revoke clients from the dashboard
• Structured logs with latency and status

How the encrypted channel works:

All sensitive payloads (the raw key, headers, request metadata) are encrypted before leaving your process using X25519 ECDH + AES-256-GCM. The raw key is never transmitted in plaintext — even TLS interception sees only ciphertext.

Your app                          apikee.dev
─────────────────────────────────────────────
1. ECDH(ephemeral_priv, server_pub)
2. HKDF-SHA256 → 32-byte AES key
3. AES-256-GCM encrypt(payload)
   POST { v, epk, iv, ct }   →   decrypt → validate → log
                              ←   AES-256-GCM encrypt(result)
4. AES-256-GCM decrypt(response)

When to use it:

• Customer-facing APIs where you issue keys to third parties
• When you need per-customer rate limiting
• When you need usage analytics and audit logs
• When you need to revoke keys before their natural expiry

# Server mode — just add two values
apikee = Apikee(
    secrets=["your-signing-secret"],
    server_key="sk_live_...",          # from apikee.dev dashboard
    project_env="my-app-production",   # project-environment slug
)

Comparison

Switching modes

Switching from local to server mode requires only config changes — no code changes in your handlers.