Skip to main content

​
Sandbox Overview

Orbit sandbox is a complete simulation environment for building and testing your integration before a single carrier sees traffic. Everything in this section works against your sandbox workspace and never bills, never rings a real phone, and never touches a live carrier. This page is your orientation: it lists what activates sandbox mode, the full list of sandbox endpoints, and points you to each tool’s own reference page.

​
What sandbox is

Sandbox mode activates when your request uses any of these three signals — the same gate every /sandbox/* route verifies before it mutates anything:
  1. A sandbox API key (prefix dv_test_sk_*), or
  2. An organisation flagged is_sandbox = true in the Orbit data plane, or
  3. The X-Test-Mode: true header on a dashboard session.
Any one is sufficient. The same three signals drive magic-number sends, sandbox number provisioning, fixture spawning, and inbound injection. Every mutation endpoint refuses a non-sandbox context with 403 SANDBOX_ONLY before it touches data. Public-key-equivalent sandbox keys use the dv_test_pk_* prefix (paired with the secret dv_test_sk_*). Live keys use dv_live_sk_*. New accounts come with a paired sandbox org — use Developer → Sandbox in the dashboard to flip between the two.

​
The sandbox surfaces

The dashboard’s Developer → Sandbox page wraps these endpoints, so you can provision numbers, spawn fixture contacts, run the Virtual Phone, and reset state from the console as well as the API. The sandbox gate on each route rejects a live context with 403 SANDBOX_ONLY.

​
How sandbox interacts with billing

Sandbox never bills. Magic-number sends report cost_usd_cents: 0, no balance is deducted, and the simulated traffic never reaches Stripe or your live wallet. Provisioning a test number, spawning a fixture, and injecting an inbound message are all free. When you flip to a live key (dv_live_sk_*), the same request shape bills normally — there is no sandbox-side billing config to clean up.

​
Sandbox to live transition

Follow the pre-launch checklist: it evaluates five ordered steps (sandbox workspace ready, live workspace ready, test key minted, integration exercised, IP allowlist configured) and reports readyForLaunch: true when every step is complete. The go-live guide walks the human sign-off; the sandbox and test mode guide covers the full sandbox-to-live path end to end.

​
Constants reference

The /sandbox/* routes are bounded by these constants:

​
Next steps