Skip to main content

Onboarding Flow

New users land on the onboarding flow the first time they sign in. The flow is two steps and is designed to take under a minute.

Step 1 — /onboarding​

The first screen confirms the user's identity and org context.

The user sees:

  • Their name and email, pulled from the identity provider (Firebase in SaaS, SSO or local auth in self-managed mode).
  • The organization they are joining, either:
    • a newly provisioned personal org (for new sign-ups), or
    • an existing org if they were invited.
  • A short value proposition reminding them what Control Zero does.

The only decision on this screen is: Continue to the next step, or Sign out if the identity does not match the user's intent.

Step 2 — /onboarding/product-select​

The user picks the product shape they want to start with. The choice sets the default dashboard layout, the default policy template, and the tier recommendation. Options:

  • Solo — individual developer, a single project, SDK-first flow.
  • Teams — multiple users, fleet management, Scout and browser extension surfaced by default.

The choice is not permanent — an admin can change it later under /settings/org via the PATCH /api/orgs/{orgID}/product-type endpoint.

What happens on completion​

When the user clicks Continue on step 2:

  1. The frontend calls GET /api/users/ensure to confirm lazy provisioning is complete. If the user is not yet in the database, the call returns 503 and the frontend retries until ready.
  2. The org, default project, and first API key are created if they did not exist already.
  3. The user is redirected to /governance/home.

Recovery​

If anything fails in step 2 (network hiccup, transient database error), the user lands on /onboarding/recover. That page retries GET /api/users/ensure on a timer and gives the user a Try again button. Once provisioning succeeds, it forwards them to the home page automatically.

Invited users​

Invited users skip the org creation step; they inherit the inviter's org and jump straight to product select.