Map: First-Run Setup (Guides & Setup Call)

A map, not instructions: the guides for the first tasks on a new instance, with what each one is for, and the setup call itself under Technical detail. This page does not set an order: Start Here lists the first tasks in the order to do them.

The Guides For The First Tasks

Each guide has the steps, the screen and button names, and what to do when a step fails. Words such as primary administrator, MFA and identity provider are in the glossary.

• 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.

• Check and adjust MFA

  Check who must use a second factor, and require or exempt chosen groups.

• Set up email

  Connect your mail server so invites, sign-in links and offers get delivered.

• Add your admins

  Invite the people who will run Zonitix and give them the right roles.

• Roles, groups and permissions

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

• Connect Okta, Entra or Google

  Link your identity provider so people sync in and access can be granted and removed.

• Set up backups

  Send encrypted backups to an S3-compatible bucket or an Azure Blob Storage container that you own, and check they run. A new instance stays locked until the first one is verified.

The Second Factor Straight After Setup

Enrol a second factor immediately. Administrators, and anyone holding the permission to manage security, to manage users or to mark approved invoices as paid, always need a second factor at sign-in. No group exemption lifts that, and neither does ticking Trust this device for 30 days. Recovery codes are issued once, with whichever factor you enrol first — store them then, because you will not see them again. How enrolment is staged is in the technical part below.

The Updates Step Of The Setup Wizard

The setup wizard has three steps: Admin Identity, Updates and Review & Launch. The Updates step asks how new releases and security patches are installed, and offers two choices:

• Update automatically, once a week, marked Recommended and already selected. You pick a day, a start time and a timezone; the wizard starts on Saturday at 02:00 in your browser’s timezone. In that window the instance backs up your data, installs the new release, checks itself, and goes back to the previous version if anything is wrong. Your administrators are emailed the day before, an hour before, at the start and at the end. Nothing is installed by itself until you have set up email.
• I’ll install updates myself. Nothing is installed until an administrator clicks Apply under System → Updates. Security fixes wait too, so that page has to be checked regularly.

The last step repeats the choice in one line, and it can be changed at any time under System → Updates. What a window does, and which releases are never installed by themselves, is on Backup, Restore & Updates.

The First Week, With The Backup Lock

A new instance is locked from the first sign-in until backups are set up. While it is locked, the screens needed to finish stay open: Backups & Recovery, Users, Groups, Roles, Security Settings, System Health, Updates, License & Entitlements and My Profile. Anyone else who signs in sees a short message that their administrator is still setting up backups. So the order of the first days is fixed by the product:

1. Day one: enrol your second factor, then connect storage you own and run a first backup. The instance unlocks when that backup has been read back from your storage and verified.
2. Within 14 days of that backup: put both recovery keys in escrow. This takes two administrators and three trustees, which is why adding a second administrator belongs in the first week. If the 14 days pass without it, the instance locks again until it is done.
3. Alongside: set up email, so backup warnings and update notices can reach you and automatic updates can run.

The full rule, including what an instance that was already live gets instead, is under Mandatory Backup Setup.

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

How Second-Factor Enrolment Is Staged

TOTP enrolment stages a pending secret and only promotes it once you confirm a code, so abandoning halfway never leaves a phantom factor on the account. Passkey registration requires user verification. The endpoints are in MFA Enforcement: TOTP Enrollment.

The Setup Call And What It Seeds

The first time you open your instance, the setup wizard asks for the one-time setup key from your “Your Zonitix instance is live” email, then walks through three steps: Admin Identity, Updates and Review & Launch. Completing it seeds the default roles and permissions and binds the primary administrator to the administrator role with isPrimaryAdmin set. It runs exactly once — afterwards the endpoint returns 403, and it holds a database advisory lock so two people cannot race it (the second caller gets 409).

setupKey is required whenever GET /api/v1/auth/setup/status reports setupKeyRequired. The password must meet the fixed policy for the primary administrator: at least 12 characters, with an uppercase letter, a number and a symbol.

updates carries the choice made on the Updates step: { "mode": "manual" }, or mode: "automatic" with day (sun to sat), time (24-hour HH:MM) and timezone (an IANA zone name). It is validated before anything is created, so a bad value answers 400 and setup does not start. It may be left out: a new instance is already seeded with automatic updates on, Saturday 02:00. The choice is applied to the update schedule the first time that schedule is read; the stored settings are under The Automatic Update Schedule.

Refusals: 400 for a missing email or password, a password below that policy, or an invalid updates value; 401 for a wrong setup key; 410 for an expired one; 429 after too many wrong keys (10 from one address within 15 minutes pause that address for 15 minutes); 409 when setup is already in progress, or with code: SETUP_KEY_NOT_CONFIGURED when the installation has no setup key; 403 once setup has been completed.

The wizard sends no securitySettings; the seeder applies the defaults: mandatory MFA on (mfaEnabled: true), a Standard password policy (8 characters, with an uppercase letter, a number and a symbol), an 8-hour session timeout and the [first_name].[last_name] naming convention. An unknown key such as mfaRequired is ignored, so MFA stays on. Only an explicit securitySettings.mfaEnabled: false sent through the API turns it off, so if you drive setup through the API rather than the wizard, confirm the setting afterwards in Security Settings.

Besides the permission catalog and the built-in roles (including administrator and standard_user), setup creates the default groups: Everyone, IT, Finance, Human Resources, HR Managers, Manager, and Security & Compliance. The wizard does not ask about groups: its last step lists them under Default groups created, and you edit them afterwards under Administration → Groups. The password policy for regular users can be changed later; the primary administrator’s cannot. The roles are listed in Roles & Permissions: Built-In Roles.