Sandbox

Sandbox

A sandbox lets you build and test an integration against real API behavior without touching your live organization’s data — and, critically, without ever triggering a real side effect (no real webhook delivery to a customer, no real message sent to a real channel, no real billing usage).

The paired-org model

Every live organization can have one paired sandbox organization. The pairing is provisioned lazily, on your first call to the provision endpoint below, and issues a sandbox-environment key in the same call — there’s no separate “enable sandbox” step.

警告

The Organization Settings → API Keys dashboard’s key-creation form still shows sandbox as a disabled placeholder option — creating a sandbox key from that form is not yet supported, and the underlying /api-keys endpoint rejects environment: "sandbox". Until that form is wired up, provision a sandbox key with the endpoint below instead.

POST /api/settings/sandbox/provision

Dashboard/session-authenticated (organization admin) — same auth as API key management, never a public API key. Request body:

Field	Type	Description
name	string	Label for the issued sandbox key (1–200 chars)
scopes	string[]	One or more scopes to grant the key

1. Call POST /api/settings/sandbox/provision with a name and scopes, authenticated as an organization admin.
2. If this is the first sandbox key for your organization, this provisions your paired sandbox organization automatically; if a pairing already exists, it just issues a new key against it. The response includes sandboxOrganizationId, provisioned (whether this call created the pairing), and the new key — with the one-time secretOnce, same as regular key creation.
3. Every request authenticated with that key is transparently routed to the sandbox organization — you never pass a separate “sandbox mode” flag; the key is the mode switch.

提示

You don’t need to track a separate sandbox organization ID. Authenticate with a sandbox key and every response — conversations, contacts, KB documents, webhook deliveries — reflects sandbox-only data automatically.

Data isolation

The isolation boundary is the organization ID itself. When a request authenticates with a sandbox-environment key, the caller’s effective organization ID is rewritten to the paired sandbox organization’s ID immediately after key verification, before any route handler runs. Every existing organization-scoped query then isolates sandbox data automatically — there is no separate environment column to filter by, and no route-by-route opt-in that could be missed.

A sandbox key can only ever resolve to its own paired sandbox — there’s no way to point a sandbox key at another organization’s data, live or sandbox.

Worker exclusion

Background workers (webhook dispatch, message delivery, billing usage aggregation, and similar) exclude sandbox organizations from every real-world side effect. Activity in a sandbox organization exercises the same code paths as live traffic — so you can trust that what you see in a sandbox test webhook or a sandbox conversation reflects real behavior — but never reaches a real third party (no outbound webhook actually delivered to your receiver’s production traffic, no real WhatsApp/LINE/Web-widget message sent).

Use the test-webhook endpoint freely in sandbox — it exercises the full signing + delivery path safely.

Rate limits

Sandbox keys always run at the lowest rate-limit tier, regardless of your live organization’s actual plan — this keeps sandbox traffic clearly bounded and cheap to run against, and prevents a sandbox integration bug from ever competing with live traffic for the same budget.

Resetting your sandbox

Reset wipes your sandbox organization’s data — conversations, contacts, KB documents, webhook events/deliveries, and similar — back to empty. It does not delete your sandbox API keys, webhook endpoint configuration, or audit history; only the data rows those configurations produced.

POST /api/settings/sandbox/reset

Requesting a reset before a sandbox pairing exists (i.e. before you’ve ever issued a sandbox key) returns an error — provision a sandbox key first.

注意

Sandbox management endpoints (/api/settings/sandbox/...) are dashboard/session-authenticated (organization admin), the same as API key management — never callable with a public API key, sandbox or live. This mirrors API key management: a key can never manage the sandbox it lives in.