Core Concepts

Authentication

How sandbox API keys work, how to authenticate per service, and how session isolation keeps your data separate.

API key format

All Ghostbox API keys use the sandbox_test_ prefix followed by a random alphanumeric string. This prefix makes sandbox keys visually distinct from production credentials, preventing accidental use in real environments.

plaintext

sandbox_test_abc123def456ghi789jkl012mno345pqr678

Keys are generated from the dashboard and shown only once at creation time. If you lose a key, delete it and create a new one.

Auth schemes per service

Each sandbox uses the same authentication scheme as the real API it simulates. Your sandbox key replaces the real API key in every case.

Service	Scheme	Notes
Stripe	`Bearer`	API key sent as a Bearer token, matching Stripe's real auth flow.
Resend	`Bearer`	Bearer token auth, same as Resend's production API.
PostHog	`Bearer`	Bearer token auth. The /decide endpoint also accepts api_key in the request body.
Mailchimp	`Basic`	HTTP Basic auth with any username and your sandbox key as the password. Matches Mailchimp's real auth.

Passing credentials

Bearer auth (Stripe, Resend, PostHog)bash

curl -X POST https://ghostbox.dev/sandbox/stripe/v1/customers \
  -H "Authorization: Bearer sandbox_test_abc123..." \
  -d "email=test@example.com"

Basic auth (Mailchimp)bash

# The username can be any string. The password is your sandbox key.
curl -X GET https://ghostbox.dev/sandbox/mailchimp/3.0/lists \
  -u "anyuser:sandbox_test_abc123..."

Basic auth with explicit headerbash

# base64("anyuser:sandbox_test_abc123...") = YW55dXNlcjpzYW5kYm94X3Rlc3RfYWJjMTIzLi4u
curl -X GET https://ghostbox.dev/sandbox/mailchimp/3.0/lists \
  -H "Authorization: Basic YW55dXNlcjpzYW5kYm94X3Rlc3RfYWJjMTIzLi4u"

Session isolation

Each API key gets its own isolated state per service. Data created with one key is invisible to other keys. This means:

Parallel test suites can run simultaneously without interference.
Each developer on a team can have their own key with independent state.
State resets when you delete and recreate a key, giving you a clean slate.

State is stored per key per service in Redis and persists across requests within a session. There is no cross-service state sharing -- creating a Stripe customer does not affect your Resend sandbox.

Rate limits and quotas

Plan	Monthly requests	API keys
Free	1,000	3
Pro	Unlimited	Unlimited

When you exceed the free tier limit, the sandbox returns a platform error with sandbox_error: "quota_exceeded". This is a Ghostbox platform error, not a simulated API error.

Invalid or missing key

If you send a request without a valid sandbox key, Ghostbox returns a 401 platform error:

json

{
  "sandbox_error": "unauthorized",
  "message": "Invalid or missing API key. Keys must start with 'sandbox_test_'.",
  "timestamp": "2026-03-28T12:00:00.000Z"
}