An isolated environment that mirrors the production API but operates on non-real data, so consumers can integrate, test, and demo without financial, reputational, or compliance consequences. Sandboxes are essential for any API that moves money, sends messages, mutates real-world state, or is subject to per-call cost — and increasingly expected even for read-only APIs as a low-friction way to evaluate.

Also known as: Sandbox Environment, Test Environment, Sandbox Mode, Test Mode, Staging

Example

- type: Sandbox
  url: https://sandbox.example.com/

Standards

• OpenAPI Initiative OpenAPI Specification 3.1
• IETF RFC 2606 — Reserved Top Level DNS Names
• Regulatory (EBA) PSD2 Regulatory Technical Standards (sandbox requirement)

OpenAPI Expression

• servers (OpenAPI 3.x) — Sandbox base URLs are declared alongside production via the servers array.
• servers[].description (OpenAPI 3.x) — Used to distinguish "Sandbox" from "Production" server entries.
• servers[].variables (OpenAPI 3.x) — Templating across environments without duplicating server entries.

Risk & Compliance

Compliance:

• PSD2 (EU) — open-banking APIs are required to expose a sandbox.
• Open Banking UK — equivalent sandbox mandate for regulated providers.
• PCI DSS — sandbox card data must use test PANs only, never real cardholder data.

Security: Sandbox credentials leaking is low-impact per call, but sandbox environments routinely allow attackers to enumerate production endpoint shapes, error messages, and rate-limit behavior. Keep sandbox infrastructure logically and operationally separate from production, and never accept production credentials in sandbox.

Tools

• Prism — Mock server generated from OpenAPI (Apache-2.0)
• Postman Mock Server — Hosted mocks
• WireMock — HTTP mock and recorder (Apache-2.0)
• Mockoon — Desktop mock server (MIT)

Suggested Metrics

• sandbox_signup_to_first_call — Time from sandbox key issuance to first 2xx response.
• sandbox_to_production_conversion — Share of sandbox accounts that promote to production credentials.
• sandbox_parity_drift — Count of endpoints or fields present in production but missing in sandbox.

Example Implementations

• Stripe — Test mode using test API keys with deterministic test card numbers.
• Plaid — Sandbox environment with synthetic financial-institution data.
• PayPal — Sandbox accounts for buyer and seller flows.
• Adyen — Test environment with deterministic card behavior and webhooks.

Related Properties

• Authentication
• Getting started
• Rate limits
• Portal

Tags

• Onboarding
• Testing
• Environments

All Common Properties