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

# Sandbox & dev environments

> Request a non-production ION environment for integration development, learn what differs from production, and promote your integration when it's ready.

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 environemnt, 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.firstresonance.io` | 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 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.

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

## Related

* [Authentication](/api-reference/authentication/overview)
* [Getting started](/api-reference/getting-started)
* [Error codes](/api-reference/error-codes)