Sandbox & dev environments - ION Manual
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 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. |
| 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.
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:
- Register production credentials. Create a new API key or OAuth app registration in the production tenant. Don’t reuse sandbox credentials.
- Swap the environment config. Update your service’s environment variables, such as
ION_BASE_URLandION_TOKEN, to point at production. - Verify with read-only operations first. Start with
meor a list query before any mutations. - 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.
- 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. 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.