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.
Overview
When you’re building an integration against the ION API, running it against your production environment is risky — a bad mutation or a runaway loop can corrupt real manufacturing data. ION offers sandbox environments for integration development: separate, isolated tenants with seeded or copied data where you can iterate without affecting production. This page covers when to use a sandbox, how to request one, what’s different from prod, and how to cut over once your integration is ready.When to use a sandbox
Use a sandbox whenever you’re:- Building a new integration (ETL, MES, ERP, Slack bot, custom dashboard)
- Testing destructive operations (bulk inventory adjustments, 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 prod credentials
Requesting access
ION sandboxes are provisioned on request. Email support@firstresonance.io with:- Why you need a sandbox (which integration is being built)
- Who needs access (a list of users / service accounts)
- What data shape you need — a clean blank org, seeded demo data, or a snapshot of your prod tenant
Differences from production
A sandbox tenant is operationally separate from prod. Treat the differences as deliberate, not bugs:| Aspect | Production | Sandbox |
|---|---|---|
| Base URL | https://api.firstresonance.io | A separate domain provided when your sandbox is provisioned |
| Auth provider | Production Auth0 / Keycloak | Separate auth instance — prod credentials do not work here |
| Data isolation | Your production tenant | Fully isolated; nothing flows between sandbox and prod |
| Rate limits | Production fair-use limits | Often more relaxed — but don’t load-test without coordinating with us |
| Feature flags | Match your tier | May expose features early for evaluation |
| Data persistence | Permanent | Sandboxes can be reset on request, or expire if dormant for long periods |
| SLA | Production SLA | None — sandboxes are best-effort |
| Webhooks | Live to your real consumers | Configurable; default is a sink so test events don’t hit your prod consumers |
401 Unauthorized against the sandbox endpoint, and vice versa.
What data is available
When the sandbox is provisioned, you choose its starting state:- Blank org — empty tenant; you populate parts/procedures/runs as part of testing.
- Seeded demo data — pre-populated with example parts, BOMs, and procedures. Best for new-developer onboarding.
- Snapshot of your prod tenant — copy of your real data at a point in time, with sensitive fields scrubbed. Best for reproducing prod-only bugs. (May be subject to compliance/legal review depending on your contract.)
support@firstresonance.io.
Best practices
- Keep sandbox creds separate from prod creds. Never reuse the same env var name for both — use
ION_SANDBOX_TOKENandION_PROD_TOKENdistinctly. - Don’t commit sandbox tokens to source control any more than you’d commit prod tokens. Sandbox data may be less sensitive but the credential is still a credential.
- Run destructive tests in sandbox. “Delete every run from the last 30 days” is fine in sandbox, terrifying in prod. Pick the right environment for the operation.
- Seed test data programmatically. A script that creates a full part → procedure → run → 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 use a header like
X-Test-Run: 1so you can 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 is working in sandbox and you’re ready for prod:- Register prod credentials — create a new API key (or OAuth app registration) in the production tenant. Don’t try to reuse sandbox credentials.
- Swap the environment config — update your service’s environment variables (
ION_BASE_URL,ION_TOKEN, etc.) to point at prod. - Verify with read-only operations first — start with
currentUseror 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; back off if they spike.
- Keep the sandbox credentials around — you’ll want them for the next iteration, hotfixes, or reproducing prod issues without touching live data.
Tips
- One integration, two environments, one codebase. Your code should branch on environment via config, not via a separate fork. Makes promoting changes a one-line PR.
- Don’t load-test without telling us. Sandboxes share infrastructure with other tenants; a sustained 10k QPS test will get throttled. If you need realistic load testing, coordinate with
support@firstresonance.iofirst. - Sandbox is not a staging environment. It’s for integration development. ION’s own staging environment (where new ION features are tested) is internal-only.
Related
- Authentication — provisioning credentials in sandbox or prod
- Getting Started — first request flow (works the same against either environment)
- Error Codes — recognizing the environment-mismatch failures