Authentication & API Keys

API Key Types#

Aforo uses two classes of API keys, distinguished by their prefix. The prefix is machine-readable — SDKs and gateway plugins automatically select the correct ingest endpoint based on which key type is present.

Key Structure

Each key is a 48-character opaque token. The prefix encodes the environment; the remaining 40 characters are a cryptographically random identifier. Keys are stored as a SHA-256 hash — Aforo cannot retrieve the plaintext after initial creation.

sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0  ← sandbox
sk_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1  ← production

Structure:
  sk_        — Aforo secret key namespace
  test_      — environment identifier (test | live)
  [40 chars] — cryptographically random token

Creating a Key#

API keys are created in the Aforo Admin Panel. Each key is scoped to a product and can optionally be restricted to specific IP ranges or rate limits.

Using Your Key#

All Aforo APIs authenticate via the standard Authorization HTTP header using the Bearer scheme. There is no session, no cookie, and no token exchange — every request carries the key directly.

HTTP Authorization Header

curl -X POST https://ingest.aforo.ai/v1/events \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc123",
    "metricId": "api_calls",
    "quantity": 1,
    "timestamp": "2026-04-18T10:00:00Z"
  }'

curl https://ingest.aforo.ai/v1/entitlements/cust_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE"

# Response:
# {
#   "allowed": true,
#   "plan": "pro",
#   "remaining_quota": 8420,
#   "quota_reset": "2026-05-01T00:00:00Z"
# }

SDK Authentication

When using any Aforo SDK, pass the key at initialization time. The SDK injects the Authorization header on every outbound request automatically.

import { AforoClient } from '@aforo/metering';

const aforo = new AforoClient({
  apiKey: process.env.AFORO_API_KEY!, // Never hardcode — always read from env
});

from aforo_metering import AforoClient
import os

aforo = AforoClient(
    api_key=os.environ["AFORO_API_KEY"]  # Never hardcode
)

Key Rotation#

Aforo supports zero-downtime key rotation via a grace period model. The old key and the new key are both valid simultaneously for 300 seconds (5 minutes), giving you time to deploy the new key to all running instances before the old one is revoked.

# Step 1: Create the new key via API (or Admin Panel)
curl -X POST https://api.aforo.ai/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "prod-key-v2", "environment": "live" }'

# Response includes the new key:
# { "key": "sk_live_NEW_KEY_HERE", "id": "key_xyz789" }

# Step 2: Update AFORO_API_KEY in your secrets manager with sk_live_NEW_KEY_HERE
# Step 3: Roll out the deployment (all instances pick up the new key)
# Step 4: After 5+ minutes, revoke the old key
curl -X DELETE https://api.aforo.ai/api/v1/api-keys/key_OLD_ID \
  -H "Authorization: Bearer sk_live_NEW_KEY_HERE"

Automated Rotation (recommended for production)

For production deployments, set up automated rotation via your cloud provider's secrets manager. AWS Secrets Manager and GCP Secret Manager both support rotation Lambdas that call the Aforo API. Contact your Aforo account team for rotation Lambda templates.

Security Best Practices#

API keys are long-lived credentials. Follow these practices to minimise exposure in the event a key is compromised.