# Sandbox

Try sending, signing and the API with test data. Each workspace has its own sandbox, kept apart from live data. Sandbox envelopes aren't legally binding and don't count toward your plan.

## Turn on Sandbox

Turn on **Sandbox** at the bottom of the sidebar, or with the **Sandbox** switch at the top of **Developers**. The sandbox opens at `/{workspace}-sandbox/`, and a banner reading **Sandbox · test data only** appears above every page. Select **Exit sandbox** in the banner, or turn the switch off, to go back to the live workspace.

The sandbox is made the first time anyone opens it. Everything you see and create there belongs to the sandbox: envelopes, templates, settings and webhook endpoints. Live data isn't shown, and nothing you do in the sandbox changes it.

Sandbox is available on every plan and to every member of the workspace. Members and roles are the same on both sides, and you manage them in the live workspace.

## What's copied and what's separate

When the sandbox is made, it starts with copies of the live workspace's:

- Workspace settings, such as reminders, the signing window and notifications
- Signing disclosure
- Brand kits, including logos
- Folders and filing rules
- Email templates
- Templates

After that the two sides are separate. Changes in the sandbox don't reach live, and changes in live don't reach the sandbox. You can use this to try other branding, folders or disclosure wording before you change live.

Saved recipients aren't copied. Each side has its own API keys: **Developers → API keys** lists live keys in the live workspace and test keys in the sandbox.

## Copy a template to live or to the sandbox

To move a template you built in the sandbox into live, open it and select **Copy to live** in the **⋯** menu. In the live workspace, **Copy to sandbox** does the opposite.

The copy includes the template's documents and goes into the folder and filing rule with the same name on the other side. It's a one-way copy: later changes to either template don't affect the other.

Branding always uses the live workspace’s kit. Switch to Live to change it; test keys cannot change branding.

## Test API keys

Test keys work on every plan. Turn on Sandbox, open **Developers → API keys** and select **Create key**. Keys made in the sandbox are test keys and start with `rk_test_`; keys made in the live workspace are live keys and start with `rk_live_`. The secret is shown once, so copy it before you close the dialog.

```bash
curl https://esignstack.app/api/v1/envelopes \
  -H "Authorization: Bearer $ESIGNSTACK_TEST_KEY"
```

The key decides the side. A test key works in the sandbox it was made in and a live key in the live workspace, whatever the app shows. A test key can create envelopes from a file or template and send them, open signing and editor sessions, and change the sandbox's folders, filing rules, message templates, saved recipients, workspace defaults and signing disclosure.

Responses from a test key name the live workspace (`"workspace": "ws_…"`) with `"livemode": false`. Platforms use the live workspace's ID in `Workspace-Id` with a platform test key (`sk_test_`) to reach that workspace's sandbox. A platform test key also changes a workspace's sandbox settings (embed and return origins, signing window, disclosure wording and consent), notification policy and brand kit with `PATCH /workspaces/{workspace}`. See the [platform integration guide](/docs/platform-integration-guide).

A few things need a live key and return `403` with `error.code: "live_key_required"` for a test key: creating, suspending or resuming platform workspaces, changing their name or metadata, any brand kit, identity providers, removing workspace members, deprovisioning, platform sign-in links and the activity log. Keys created through the API with a test key are always test keys.

Sandbox envelopes can't be moved to live. When your integration is ready, create a live key and use it the same way. Templates can be copied to live as described above.

When you connect an AI agent, the consent screen asks whether it works in **Live** or **Sandbox**. A Sandbox connection is listed and revoked on the sandbox's **API keys** page. See [MCP](/docs/mcp).

See [API quick start](/docs/api-authentication) for abilities and request basics.

## Who can receive test emails

Sandbox emails are only delivered to **verified members of the workspace**, including you. Email to any other address isn't sent. To test a signing flow, add a member's email as the recipient, open the invitation from that inbox and sign as that person. The signer still goes through any verification the envelope asks for.

SMS verification isn't available in the sandbox. Sending a test envelope with an SMS-verified recipient fails, and the API returns `422`. Use email verification or an access code instead.

Sandbox envelopes never appear in anyone's signer portal, and [verification](/docs/verification) doesn't recognise them.

## How test envelopes look

- Email subjects start with `[TEST]`, and the body says **TEST — not legally binding**.
- Every page of the PDF, including the certificate, is marked **TEST — not legally binding**.
- Completed test PDFs don't get the production seal or timestamp.

Don't send test PDFs to anyone as signed agreements.

## What isn't counted

Sandbox envelopes aren't counted toward any allowance. This covers sends in the app, kiosk and share-link submissions, bulk sends, API and MCP sends, and signing sessions. They don't use or buy envelope packs, and they don't trigger allowance emails. See [Plans and billing](/docs/plans-and-billing).

## Webhooks

Sandbox events have `"livemode": false` and only go to test webhook endpoints. Live endpoints never receive them. A workspace's test endpoints are the sandbox's own: add one in **Developers → Webhooks** while in the sandbox, or create it with a test key. Platform endpoints are set to **Live** or **Test** when they're created.

```json
{
  "object": "event",
  "type": "envelope.completed",
  "livemode": false,
  "data": {
    "object": {
      "object": "envelope",
      "livemode": false,
      "status": "completed"
    }
  }
}
```

**Send test event** sends a sample event in the endpoint's own mode. A sample sent to a live endpoint has `"livemode": true`. See [Webhooks](/docs/webhooks).

## Delete sandbox data

Owners and admins can clear out test data. In the sandbox, go to **Developers → Overview** and find **Delete sandbox data**. Type `DELETE SANDBOX DATA` and select **Delete sandbox data**.

This permanently deletes from the sandbox:

- Envelopes, including those in the trash, with their recipients and history
- Uploaded files and templates
- Editor sessions
- Events, test webhook endpoints and their deliveries

The sandbox keeps its settings, brand kits, folders, filing rules, message templates, saved recipients and test API keys. Live data and members aren't touched.

> [!NOTE]

After deleting, use a new `Idempotency-Key` for API requests. A key you used before may replay its earlier response for up to 24 hours.
