Cybersecurity Essentials

A single leaked API key can turn a protected endpoint into an open data pipe. This section documents how to authenticate API requests safely using API keys, rotate them on a schedule, and constrain access with least-privilege scopes for developer workflows.

Overview

This section covers API key authentication mechanics, required request headers, and how to structure scopes so keys only perform the minimum actions needed. Use it when integrating service-to-service or client-to-API calls where OAuth is not required or is unavailable.

Quick Reference

• Authentication header (common pattern): `Authorization: ApiKey `
• Rotation model: maintain two active keys per principal during cutover (old + new) to avoid downtime.
• Least-privilege scopes: assign narrow scopes per key (e.g., read-only, specific resource prefix).
• Key lifecycle endpoints (typical):
• `POST /v1/keys` create key (returns `keyId`, `secret`)
• `POST /v1/keys/{keyId}/rotate` mint new secret
• `POST /v1/keys/{keyId}/revoke` disable key
• Rate limits: enforced per key and/or per IP; 429 indicates throttling.

Parameters

Code Example

import os
import time
import requests

API_BASE = "https://api.example.com"
API_KEY_SECRET = os.environ["EXAMPLE_API_KEY_SECRET"]  # rotate via deployment secret store
API_KEY_ID = os.environ.get("EXAMPLE_API_KEY_ID")      # optional but useful for audit

# Least-privilege scopes are assigned at key creation/rotation time.
# Example scopes: "payments:read payments:refunds:create" (do not over-broaden).

headers = {
    "Authorization": f"ApiKey {API_KEY_SECRET}",
    "Accept": "application/json",
}
if API_KEY_ID:
    headers["X-API-Key-Id"] = API_KEY_ID

params = {
    "limit": 50,
    "cursor": None,
}

# Request will fail with 401 if the key is revoked/invalid, and 403 if scopes are insufficient.
resp = requests.get(f"{API_BASE}/v1/payments", headers=headers, params=params, timeout=10)

if resp.status_code == 429:
    # Rate limit: use Retry-After if provided; otherwise apply backoff.
    retry_after = int(resp.headers.get("Retry-After", "1"))
    time.sleep(retry_after)
    resp = requests.get(f"{API_BASE}/v1/payments", headers=headers, params=params, timeout=10)

resp.raise_for_status()
data = resp.json()
print(data["items"])

Response Format

{
  "requestId": "req_01J6Y7K2X9A1B3C4",
  "status": "success",
  "items": [
    {
      "id": "pay_12345",
      "amount": 1099,
      "currency": "USD",
      "createdAt": "2026-07-04T12:34:56Z"
    }
  ],
  "page": {
    "nextCursor": "eyJjdXJzb3IiOiJ..."}
  }
}

Field notes

• `requestId`: correlates logs across gateway and application.
• `items`: resource list governed by the granted scopes.
• `page.nextCursor`: present when pagination continues.

Notes & Best Practices

• Rotation cutover: keep the old key active for `rotation_window_seconds` (default 300) while deployments update secrets; revoke immediately after cutover to reduce exposure.
• Scope boundaries: treat scopes as enforcement units; avoid wildcard scopes (e.g., `` or broad `read:`) unless the provider explicitly supports scoped resource filters.
• Error handling: `401` = invalid/revoked key; `403` = authenticated but insufficient scopes; `429` = rate limit (use `Retry-After` when present).
• Storage and audit: store key secrets in a managed secret store; log `X-API-Key-Id` (not the secret) and alert on anomalous request volume per key.

KeyScope Rotation Playbook usage of scoped keys and controlled rotation sets up the next layer: consistent authorization decisions across endpoints and services without expanding blast radius.