> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox: orientation for test mode

> How Orbit sandbox works — what activates it, the full list of sandbox endpoints, how it interacts with billing, and the path from sandbox to live.

# 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

| Surface                           | Endpoint                                       | What it does                                                                                                                |
| --------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Magic numbers reference           | `GET /sandbox/numbers`                         | Returns the 10-state magic-number catalog                                                                                   |
| Delivery-state simulation         | `POST /messages/*` targeting a magic recipient | The recipient's trailing digit picks the DLR scenario — see [magic numbers](/sandbox/magic-numbers)                         |
| Pre-launch checklist              | `GET /sandbox/pre-launch-checklist`            | Five-step shared go-live gate — see [pre-launch checklist](/sandbox/pre-launch-checklist)                                   |
| Reset                             | `POST /sandbox/reset`                          | Wipes contacts, conversations, and messages, and releases sandbox numbers                                                   |
| Provision numbers                 | `POST /sandbox/provision-numbers`              | Mints deterministic fictional `+1(555)01XX` test numbers                                                                    |
| Spawn fixture contacts            | `POST /sandbox/spawn-fixture-contacts`         | Seeds deterministic fixture contacts, optionally with conversations                                                         |
| Inbound injection (Virtual Phone) | `POST /sandbox/inbound`                        | Simulates an inbound SMS / MMS / WhatsApp message into your inbox — the "Virtual Phone" the dashboard's sandbox page embeds |

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](/sandbox/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](/guides/go-live-checklist) walks the human sign-off; the [sandbox and
test mode](/guides/sandbox-test-mode) guide covers the full sandbox-to-live
path end to end.

## Constants reference

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

| Constant                   | Value                    | What it bounds                                                 |
| -------------------------- | ------------------------ | -------------------------------------------------------------- |
| `MAX_PROVISION_NUMBERS`    | `25`                     | Max numbers per `POST /sandbox/provision-numbers` call         |
| `MAX_FIXTURE_CONTACTS`     | `50`                     | Max contacts per `POST /sandbox/spawn-fixture-contacts` call   |
| `SANDBOX_INBOUND_CHANNELS` | `sms`, `mms`, `whatsapp` | Channels `POST /sandbox/inbound` (Virtual Phone) can inject on |
| `RATE_LIMIT_AUTH_WRITE`    | `60` req/min per tenant  | Applies to every sandbox mutation endpoint                     |

## Next steps

* [Quickstart](/quickstart) — get your first API key and make your first
  sandbox call
* [Magic numbers](/sandbox/magic-numbers) — the 10 delivery-state scenarios
  keyed by trailing digit
* [Pre-launch checklist](/sandbox/pre-launch-checklist) — the five-step go-live
  gate
* [Sandbox and test mode](/guides/sandbox-test-mode) — the full sandbox
  walkthrough