Dev tenants and test mode
A dev tenant is a separate ARC organization for building and testing your app. It holds synthetic data only and is always in test mode, so nothing you do in it reaches a real customer.
Provision a dev tenant
Sign in to your own organization as a user with the settings:apps:manage permission (Owner or Admin by
default; the Custom Apps plan switch must be on), then call:
mutation {
provisionDevTenant(input: { name: "My app sandbox", subdomain: "myapp-sandbox" }) {
organizationId
subdomain
onboardingId
}
}
- The subdomain follows the same rules as signup and must be free.
- You are the dev tenant's first user (its Owner), with your own email address.
- It copies your organization's country, currency and time zone, and nothing else.
- A dev tenant cannot provision another dev tenant.
- The dev tenant is born with the Custom Apps switch on, so you can build apps in it straight away. Other app switches (app extensions, the storefront API) stay off. Your own organization's settings do not change.
Setup runs in the background, exactly like a new signup. Follow it at GET /onboarding/progress/<onboardingId>
(server-sent events). When it completes, GET /onboarding/status/<onboardingId> returns your first sign-in
tokens. After that, sign in as usual with a sign-in code: account email to the dev tenant's own staff is
delivered (see below).
What a dev tenant contains
The usual new-workspace setup (roles, units, a warehouse, tax presets for the country), plus four synthetic
partners: three customers and one supplier, named ZZ Dev …, tagged synthetic. They have no email address
or phone number. Never import real customer data into a dev tenant.
Test mode
Every dev tenant is in test mode. While an organization is in test mode:
| Channel | What happens |
|---|---|
| Account email (sign-in codes, password resets, invites) to the organization's own active staff | Delivered, so you can sign in. Every recipient must be staff of that organization. |
| Every other email (documents, reports, SMTP test sends, and account email to anyone else) | Kept in a sink. Never sent. The send reports success so your flow carries on. |
| WhatsApp messages | Kept in the sink. Never sent. |
| Webhooks | Delivered, with X-ARC-Environment: test. |
Every webhook carries X-ARC-Environment: test from a test-mode organization, live from any other. Use
it to keep test traffic out of your production data:
const result = verifyWebhook({ rawBody, headers, secret });
if (result.ok && result.environment === 'test') {
// route to your sandbox, never to production
}
A customer you add to a dev tenant never receives mail from it, sign-in codes included.