Environments: Sandbox vs Production

Aforo runs two fully isolated environments — Sandbox and Production. They share no data, no customer records, and no billing state. The environment is determined entirely by which API key you use — no configuration flag, no environment header, no separate base URL to manage.

Sandbox Environment#

The sandbox is a full-fidelity replica of production. Every feature — metering, entitlements, margin guards, rate plans, invoicing — works identically. The only difference is that no real charges are generated. It is safe to fire any event, create any customer, or simulate any billing scenario without financial consequence.

What the Sandbox Simulates Accurately

The sandbox is not a mock. It runs the same metering pipeline, the same rating engine, and the same entitlement cache as production. The following behaviors are identical in both environments:

Production Environment#

The production environment processes real usage events that generate real charges on real customer invoices. Every event is rated against your live rate plans, accrues to the customer's invoice ledger, and is included in the next billing cycle.

Switching Environments#

Switching between environments requires only changing the AFORO_API_KEY environment variable. No code changes. No config file updates. No redeployment of your application logic — only the secrets layer changes.

# Sandbox — safe for local dev and CI
AFORO_API_KEY=sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
AFORO_PRODUCT_ID=prod_sandbox_abc123

# Production — real billing, handle with care
AFORO_API_KEY=sk_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1
AFORO_PRODUCT_ID=prod_live_xyz789

The SDK and all gateway plugins inspect the key prefix at startup and route to the correct ingest endpoint automatically. You do not need to set a separate AFORO_INGEST_URL — that is handled for you.

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

const aforo = new AforoClient({
  apiKey: process.env.AFORO_API_KEY!,
  // No ingestUrl needed — SDK reads the key prefix:
  //   sk_test_ → ingest-sandbox.aforo.ai
  //   sk_live_ → ingest.aforo.ai
});

// This works identically in sandbox and production.
// The key determines where events go.
await aforo.meter({ customerId: 'cust_123', metricId: 'api_calls', quantity: 1 });

Environment Variables#

The following environment variables are recognised by Aforo SDKs and gateway plugins. All are optional except AFORO_API_KEY.

Multi-Environment CI Setup

For CI/CD pipelines that deploy to multiple environments, inject the correct key per environment via your CI provider's secrets:

jobs:
  deploy-staging:
    environment: staging
    steps:
      - run: npm run deploy
        env:
          AFORO_API_KEY: ${{ secrets.AFORO_SANDBOX_KEY }}  # sk_test_...

  deploy-production:
    environment: production
    steps:
      - run: npm run deploy
        env:
          AFORO_API_KEY: ${{ secrets.AFORO_LIVE_KEY }}     # sk_live_...

Data Isolation#

Sandbox and production environments are fully isolated at the infrastructure level. They run on separate database, cache, streaming, and analytics infrastructure. There is no shared state and no data cross-contamination possible.

Sandbox Dashboard

The Aforo Admin Panel shows sandbox and production data in separate tabs. Events fired with a sk_test_ key appear only in the Sandbox tab and are never visible in the Production tab — even if the customer ID happens to match a real production customer. The environment boundary is enforced server-side by the key, not by the dashboard UI.

Aforo Dashboard
├── [Sandbox]     ← Events from sk_test_ keys appear here
│   ├── Event Log
│   ├── Customers
│   └── Invoices (simulated — no real charges)
│
└── [Production]  ← Events from sk_live_ keys appear here
    ├── Event Log
    ├── Customers
    └── Invoices (real — billed to payment processor)