​

Onboarding wizard: tenant provisioning and white-label joins

​

1. Where the wizard fits in the tenant journey

​

2. The wizard steps, as the controller derives them

curl "https://api.orbit.devotel.io/api/v1/onboarding/status" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const { data } = await orbit.request("GET", "/onboarding/status");
// Wait for head-of-queue completion before continuing a scripted setup.
console.log(data.nextIncompleteStep); // { id, label, ctaUrl } or null

​

Marking a step complete or skipping it

curl -X POST "https://api.orbit.devotel.io/api/v1/onboarding/complete-step" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"stepId": "first_contact_created"}'

curl -X POST "https://api.orbit.devotel.io/api/v1/onboarding/skip-step" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"stepId": "payment_method_added"}'

​

The provisioning-status gate

• emailVerified — your email confirmation landed.
• tenantSchemaReady — the workspace’s tenant schema finished provisioning.
• trialCreditsGranted — informational only; never a blocking signal.
• apiKeySeeded — at least one active API key exists.
• allReady — true once the three blocking booleans (email, schema, API key) are green.

​

3. The white-label join path

1. Re-verifies the host against the active custom-domain registry — a host that is not a live white-label domain is rejected (the host arrives over an attacker-controllable header, so it is never trusted without a registry lookup).
2. Confirms the domain’s owning tenant is live and finished provisioning.
3. Binds you into that tenant at the least-privilege seat — replaying the call when you already belong there is an idempotent no-op.
4. Retires the auto-provisioned placeholder workspace so it never lingers in your org switcher.

• Joiners land as user, not admin. Promote them under Settings → Team if they need more (see Organization team management).
• The joiner’s provisioning signals (tenant schema, API key) are satisfied by the owner’s tenant from day one, so their checklist starts at the workspace-name/e-mail steps and the provisioning panel resolves immediately.

​

4. The provisioning degradation model

• Every probe degrades per-step. If one underlying read fails (a connection blip, a briefly absent schema), that step resolves to “not complete” and every other step still resolves normally. You see an honest checklist with one understated row, never a 500.
• The whole checklist degrades to an all-incomplete 200 when the derivation exceeds its deadline or the database is briefly unavailable. That response is deliberately not cached, so the next poll re-derives the true state the moment the backend recovers. Treat an unexpectedly-empty checklist as exactly that: one transient cycle.
• Provisioning-gap errors — a brand-new org whose schema is still being created — return the same neutral 200. The onboarding read endpoints opt out of the hard “tenant schema not ready” 503 the rest of the API enforces, because a still-provisioning workspace genuinely has no rows yet.
• Degraded provisioning reads are logged server-side so a persistent backend issue is distinguishable from “user has not done the step yet” — an understated row that survives more than one cache cycle is a platform signal, not a checklist item to chase.

​

5. Webhook and progress signaling

• Onboarding checklist (status, provisioning-status, sms-checklist) is pull-based and per-(workspace, user): “what has this workspace done, and what is next.” It is cached and derivation-driven — there are no webhook events for “step N completed.”
• Status timeline (GET /api/v1/onboarding/status-timeline) is the verification side of the same story: account-KYC, 10DLC, country-profile, and per-number gates, each with a blocker and a resolve link — see Onboarding status timeline.
• Webhook events fire for the underlying activity — message.sent / message.delivered, kyc_decision notifications, compliance.10dlc.campaign.suspended, and the rest of the catalog in Webhook events. If you want automation on “the workspace sent its first message,” subscribe to message.sent and detect the first occurrence yourself; the checklist is not the event bus.

​

6. Post-wizard state: the sandbox and your first channel

1. Sandbox mode is on before you connect anything. Every account starts with a free sandbox where traffic external to your account is simulated — messages to magic numbers validate and acknowledge without touching a carrier, so you can test end-to-end with zero risk of carrier rejections. The sandbox test mode guide and the magic-numbers playbook cover the test numbers at your disposal.
2. Connect your first real channel through the Messages hub — SMS, WhatsApp, RCS, Telegram, Email all share the same connect-send-verify shape. The connect your first channel tutorial walks it end to end, from the hub’s Connect button to a delivered message and a handled reply.
3. KYC approval unlocks live traffic. Submit under Settings → KYC (see the organization KYC guide); once approved, the trial credit grants and you can flip out of sandbox. The go-live checklist is the final sweep before production.