# Sandbox Documentation

A sandbox is a separate, isolated ION tenant with seeded or copied data. Use one to build and test an integration against the ION API without affecting production.

## When to use a sandbox

Use a sandbox whenever you’re:

- Building a new integration, such as an ETL, MES, ERP, Slack bot, or custom dashboard.
- Testing destructive operations, such as bulk inventory adjustments or mass run cancellations.
- Reproducing a customer support issue without touching live data.
- Running automated CI tests against the API.
- Onboarding a new developer who needs API access without production credentials.

If you’re only reading data for a one-off report or analysis, production with a read-only API key works too. If you’re writing data, use a sandbox first.

## Requesting access

To request a sandbox environment, contact [support](https://support.firstresonance.io/) with:

- Why you need a sandbox, including which integration you’re building.
- Who needs access, as a list of users or service accounts.
- What data shape you need: a blank org, seeded demo data, or a snapshot of your production tenant.

A typical sandbox is provisioned within a few business days. Sandboxes don’t count against your production seat license. Heavy or long-lived sandbox usage can have contract implications. The support team confirms this if it applies.

## Differences from production

A sandbox tenant is operationally separate from production.

| Aspect            | Production                                  | Sandbox                                           |
|-------------------|---------------------------------------------|---------------------------------------------------|
| Base URL          | `https://api.buildwithion.com`             | A separate domain provided when your sandbox is provisioned |
| Auth provider      | Production auth provider                    | A separate auth instance. **Production credentials do not work here.** |
| Data isolation     | Your production tenant                      | Fully isolated. Nothing flows between sandbox and production. |
| Rate limits       | Production fair-use limits                   | Often more relaxed. Coordinate load testing with [support](https://support.firstresonance.io/). |
| Feature flags      | Match your tier                             | Can expose features early for evaluation           |
| Data persistence   | Permanent                                   | Can be reset on request. Sandboxes expire if dormant for long periods. |
| SLA               | Production SLA                              | None. Sandboxes are best-effort.                   |
| Webhooks          | Live to your real consumers                 | Configurable. The default is a sink, so test events don’t reach your production consumers. |

The most common stumbling block is auth credentials. API keys and OAuth apps are environment-scoped, so you have to register them inside the sandbox tenant. Using production credentials against the sandbox (or the other way around) will result in `401 Unauthorized` errors.

## What data is available

When the sandbox is provisioned, you choose its starting state:

- **Blank org**: an empty tenant. You populate parts, procedures, and runs as part of testing.
- **Seeded demo data**: pre-populated with example parts, BOMs, and procedures. Best for new-developer onboarding.
- **Snapshot of your production tenant**: a copy of your real data at a point in time, with sensitive fields scrubbed. Best for reproducing production-only bugs. This option can be subject to compliance or legal review depending on your contract.

Sandboxes don’t auto-sync from production. To get a fresh snapshot months later, request a refresh from [support](https://support.firstresonance.io/).

## Best practices

- Seed test data programmatically. A script that creates a full part, procedure, run, and installation chain is easier to re-run than rebuilding state by hand each time the sandbox resets.
- Tag webhook payloads. When testing webhooks, prefix the consumer URL or set a header such as `X-Test-Run: 1`. This lets you distinguish sandbox-driven events from real ones in your downstream system.
- Smoke-test your integration after every sandbox reset. Even fully scripted setup occasionally drifts.

## Promoting an integration from sandbox to production

When your integration works in sandbox and you’re ready for production:

1. **Register production credentials.** Create a new API key or OAuth app registration in the production tenant. Don’t reuse sandbox credentials.
2. **Swap the environment config.** Update your service’s environment variables, such as `ION_BASE_URL` and `ION_TOKEN`, to point at production.
3. **Verify with read-only operations first.** Start with `me` or a list query before any mutations.
4. **Roll out gradually.** If your integration writes to ION, ramp the volume rather than turning it on at full throughput. Watch for 4xx error rates and back off if they spike.
5. **Keep the sandbox credentials.** You’ll want them for the next iteration, for hotfixes, or for reproducing production issues without touching live data.

Coordinate load testing with [support](https://support.firstresonance.io/). Sandboxes share infrastructure with other tenants. ION throttles sustained high-volume tests, such as 10,000 QPS.

A sandbox is not a staging environment. It’s for integration development. ION’s own staging environment, where new ION features are tested, is strictly internal.