Skip to content
Documentation

API Key Handling

SotsAI API keys identify your organization and authorize access to the API. Treat them like production credentials (similar to database passwords or cloud service keys).

This page covers best practices to prevent leaks, reduce blast radius, and support rotation.

Golden rules

Section titled “Golden rules”

  1. Never expose API keys in client-side code

    • No frontend JavaScript bundles
    • No mobile apps
    • No public repositories
    • No browser tool calls directly to SotsAI (unless you accept the risk explicitly)

  2. Keep keys server-side

    • Your backend (recommended)
    • Your API gateway
    • Your secure LLM orchestration layer

  3. Assume keys will leak someday

    • Design for rotation
    • Add monitoring
    • Limit privileges where possible
Section titled “Recommended architecture”
Section titled “Option A (recommended): Your backend calls SotsAI”
User → Your App/LLM → Your Backend → SotsAI

Advantages:

API key never leaves your infrastructure

easier auditing, rate limiting, and logging

Option B: API gateway calls SotsAI

Section titled “Option B: API gateway calls SotsAI”
User → Your App/LLM → API Gateway → SotsAI

Advantages:

  • central policy enforcement (auth, throttling, logging)
  • consistent across multiple internal services

Storage best practices

Section titled “Storage best practices”

Store API keys in a secret manager or encrypted vault, not in code.

Recommended:

  • cloud secret managers (GCP/AWS/Azure)
  • HashiCorp Vault
  • encrypted environment variables managed by your deployment system
  • …

Avoid (classic):

  • .env committed to git
  • hardcoded constants
  • shared docs / Notion pages
  • sending keys via chat/email

Runtime best practices

Section titled “Runtime best practices”

Use keys only from server-side environment

Section titled “Use keys only from server-side environment”
  • load keys at process start (env var / secret manager)
  • inject into outgoing requests to SotsAI
  • never log the key

Protect logs

Section titled “Protect logs”

Make sure your logs do not accidentally capture:

  • request headers (if the key is in headers)
  • full request bodies (if you include sensitive context summaries)

Implement log redaction rules for:

  • authorization headers
  • any field named api_key, authorization, token

Rotation strategy

Section titled “Rotation strategy”

Even if you rarely rotate keys, you should be able to rotate them quickly.

Recommended rotation pattern:

  1. Provision a new key
  2. Deploy it alongside the old key (dual-key window)
  3. Switch traffic gradually
  4. Revoke the old key

If you operate multiple environments:

  • use different keys for dev, staging, prod
  • never reuse production keys in staging

Detecting compromise

Section titled “Detecting compromise”

Signals you should monitor:

  • sudden spikes in request volume
  • requests from unexpected IP ranges (if you enforce IP allowlists)
  • increased quota usage without corresponding internal activity
  • repeated authentication failures

If compromise is suspected:

  • rotate keys immediately
  • review recent usage and logs
  • tighten gateway rules (rate limiting, IP allowlist)
  • validate that no keys are embedded in client apps

Even if your system is “just one key today”, you can still reduce damage:

Section titled “Even if your system is “just one key today”, you can still reduce damage:”
  • separate keys per environment
  • separate keys per product surface (e.g., internal tools vs customer-facing)
  • apply stricter rate limits on higher-risk surfaces
  • restrict who can access secrets (operators only)

Tool-calling considerations

Section titled “Tool-calling considerations”

If you use LLM tool calling:

  • keep the API key outside the model context
  • the LLM should produce only the tool payload
  • your tool runner injects authentication securely

This avoids accidental key exposure through:

  • prompt injection
  • tool-call echoing
  • logs and traces

Summary checklist

Section titled “Summary checklist”
  • API key is stored in a secret manager (not in code)
  • Key never reaches the browser or client apps
  • Logs redact authorization headers and sensitive fields
  • You can rotate keys without downtime
  • Monitoring exists for usage spikes and anomaly patterns
  • Separate keys exist for dev/staging/prod