Skip to content

Setup Wizard

The first time you open NexaDesk in a browser, you'll be taken to the setup wizard at /setup. It walks you through creating your admin account, branding, and email — but first, it asks for your setup token.

Step 0 — The setup token

Because a brand-new install has no admin account yet, the wizard proves that you control the server before it lets anyone configure anything. When the API starts on a fresh install, it prints a one-time token to its logs:

============================================================
  FIRST-RUN SETUP TOKEN: kF3xR9_wQ2mZpT8vLnDb4Ys6

  The setup wizard requires this token to configure the
  admin account. Retrieve it any time before setup completes
  with:  docker compose logs api | grep -A1 'SETUP TOKEN'
============================================================

Retrieve it on the server:

docker compose logs api | grep -A1 "SETUP TOKEN"

Paste it into the wizard's token screen and continue.

Lost the token? Logs rotated?

Restart the API — the token is re-printed on every startup until setup completes: 

docker compose restart api && docker compose logs api | grep -A1 "SETUP TOKEN"

Why this exists

Without the token, whoever reached your server's URL first could claim the admin account. The token ensures only someone with shell access to the host can complete setup. It is deleted the moment the wizard finishes, and repeated wrong guesses are rate-limited.

Step 1 — Admin Account

Create the primary administrator: full name, email address, and a password (minimum 8 characters). This replaces the seeded default admin credentials.

Step 2 — Branding

Set your company name, primary brand colour, and portal URL. You can refine this later (including logo and favicon) under Settings → Branding.

Step 3 — Email Integration

Connect the mailbox that will receive support requests:

  • SMTP/IMAP — enter host, port, credentials for both directions; the wizard tests the connection live before proceeding.
  • Microsoft 365 — M365 uses OAuth, which is completed after the wizard under Settings → Channels (the wizard will remind you).
  • Skip for now — you can connect email any time later.

Step 4 — Review & Complete

Confirm your settings and hit Complete Setup. You'll be redirected to the login page — sign in with the admin account you just created.

Staff accounts require 2FA

On first login, admins and technicians are prompted to enrol a TOTP authenticator app (Google Authenticator, Authy, 1Password…). This is mandatory for staff accounts.

After the wizard

The setup endpoints lock permanently once the wizard completes — the token is gone and all configuration from here on requires an authenticated admin. Continue with the First Steps Checklist.