Map: Onboarding & Offboarding (Guides & Calls)

What lies between an empty instance and a new employee with accounts on day one, and a leaver whose sign-in is blocked the moment offboarding starts. For the order to do the first tasks in, use Start Here: this page does not keep an order of its own.

What This Page Covers

Each guide has the steps, the screen and button names, and what to do when a step fails.

• First sign-in on a new instance (administrator)

  Sign in to your new instance, choose how updates are installed, secure the primary admin account, and see why backups come next.

• Use the org chart

  See who reports to whom, move someone under a new manager, add dotted-line managers, and compare dated snapshots.

• Create a persona

  Define what a role gets on day one: apps, licences and hardware.

• Onboard your first hire

  Start a new person’s onboarding and work their accounts, apps and devices through to day one.

• Offboard someone

  Block a leaver’s sign-in, revoke their access and track what still needs returning.

• Work through workflow tasks

  Find the runs waiting on you, claim a step, tick the checklist, approve, and check History.

• Customize a workflow

  Add, reorder or skip steps, set the automation mode, and get a second approver to put it live.

• Roles, groups and permissions

  What roles, groups and permissions do, the built-in set, custom roles, group MFA and one-off grants.

Where The Rules Are

The rules behind these subjects are kept on the reference page that owns each one, so they are written once: one line each below, with the page to read. After the list come how a first onboarding and an offboarding start and what happens at once. The offboarding call itself is in the technical part below.

• The setup call and the first sign-in

  The wizard runs once, behind a lock, and seeds the roles, the default groups and the primary administrator, who then enrols a second sign-in factor. First-Run Setup: The Setup Call And What It Seeds, MFA Enforcement

• Roles, direct grants, groups and personas

  A person’s permissions are what their roles grant plus any direct grants; a group organises people, can force MFA for its members and scopes password policy; a persona is not access control. Roles & Permissions: How Access Is Decided

• Workflow versions and the approval gate

  Editing an approved workflow forks a new version, and promoting it needs a separate permission, a fresh re-authentication and, unless the approver is on the administrator role, a different person from its author. Visual Workflow Builder, API Reference

• How runs move from step to step

  The five pipelines a new instance ships with, the automation mode of each, run and step states, retries and the emails a run sends. How Workflows Run (Orchestration), Signed Offer To Onboarding (Zero-Touch)

• Personas and the provisioning-plan preview

  The persona endpoints, the two preview calls that change nothing, and the rule that sorts each item into an automatic step or a dated task for IT. Personas (Job Blueprints)

• The org chart and its snapshots

  The chart is drawn from each person’s manager; a snapshot captures all users with their roles and groups, plus aggregates by department and status. Org Chart

• Updating and offboarding an account

  The user endpoints, the protections on the primary administrator and the offboard call. User Accounts: Offboard

Your First Onboarding

An onboarding run starts in one of four ways: Start a run on Workflow Tasks; the Onboard icon on a person’s row in Administration → Users (for someone pre-boarding, or a rehire); your identity provider through SCIM, when Start onboarding for new people is switched on; or a candidate signing their offer in Recruitment, which marks the offer accepted and starts the run — creating the employee record and an onboarding task dated to their start date.

Each line item on the persona is then sorted into one of two piles:

• Automated — only when the item maps to a provider you have actually connected and activated, and that provider supports real provisioning.
• A dated task for a human — everything else: unmapped items, providers you have not connected, and all physical hardware.

Whether an “automated” step runs by itself depends on the workflow’s automation mode. Every new instance ships Master Onboarding as Accounts automatic: HR intake, IT setup and manager approval still wait for a person, and once the manager has approved, the account steps for your connected providers run on their own. Offboarding, mover and access workflows ship as Runs manually, where every step waits for someone in the owning queue. You change the mode per workflow in Workflow Builder → Manage → Automation. Steps enforce queue ownership and are idempotent, so a double-click cannot provision twice.

Offboarding

Offboarding starts in one of three ways: a person clicks Offboard (this needs the permission to manage users); a scheduled termination date arrives; or a connected directory (Okta, Google Workspace, Microsoft Entra ID, LDAP) or your identity provider through SCIM deactivates the person, which runs the same full offboarding for accounts that directory owns. You cannot offboard yourself, and the primary administrator is never offboarded by any of the three.

The moment you trigger it, and before any workflow step runs: the account status flips to offboarded, which blocks sign-in; and every role is stripped. Only then does the task queue open, mirroring onboarding in reverse — automated revocation where a provider is connected, dated reclaim tasks everywhere else, due by the last day. Triggering it twice while one is running does nothing.

If something here is not working as you expect, start with When something goes wrong.

Offboarding Run Mechanics

Offboarding is one call; its short form is on User Accounts: Offboard. The Offboard button and the call both need the manage_users permission. The lastDay field is optional; when omitted, reclaim tasks fall back to their own due dates or the literal “the last day” in notifications.

Two status codes carry the outcome, and the distinction is load-bearing — access revocation and run creation are separate results:

Immediate termination. Sending immediate: true makes the run’s revoke steps execute at once instead of waiting for someone to work the queue. It needs a reason of at least five characters, or the call is refused with 400. The answer is also 202, not 201, when that forced revocation revoked nothing, failed, or left gaps: the person is out of Zonitix but an account in a connected app is still open.

Guards. A manage_users operator cannot offboard themselves — the controller compares the caller’s id to :id and returns 403 “You cannot offboard your own account.” before any state changes. The primary administrator is refused deeper in, with its own 403. On the first successful call, and before any workflow step runs, the account status flips to offboarded (which blocks sign-in on the next request), and every role assignment is stripped. Re-triggering while a run is open is idempotent — it returns without creating a second run, access already being revoked.