Super Admin and authentication setup

Most of Chorus is workspace-scoped, but one role sits above the workspaces: the Super Admin. It is how you create workspaces and turn on single sign-on (SSO) for your team. This guide is for whoever runs the Chorus deployment; end users who just need to sign in should read Account and workspace.

Enable the Super Admin

The Super Admin is a platform-level account, separate from any workspace. You enable it on the server with two environment variables — the admin email and a bcrypt hash of the admin password:

SUPER_ADMIN_EMAIL="admin@example.com"
SUPER_ADMIN_PASSWORD_HASH="$2b$10$..."   # bcrypt hash of your password

Generate the hash with a one-off command, for example:

node -e "console.log(require('bcryptjs').hashSync('your-password', 10))"

Keep the bcrypt hash in your deployment’s secret store. Admin sessions also need a secure NEXTAUTH_SECRET: for a single instance, the npm chorus launcher and the Docker entrypoint can generate and persist it for you. With more than one replica, set the same value explicitly on all of them. See Docker session secrets.

Sign in as Super Admin

There is no link to the admin panel inside the app — you reach it through the normal sign-in screen. Enter the Super Admin email; Chorus recognizes it and asks for the admin password on a dedicated step, then opens the Super Admin panel. The admin session is independent of any workspace and is shorter-lived than a normal session, so you sign in again periodically.

The Super Admin has no workspace boundary

Unlike a workspace admin agent, the Super Admin is not scoped to one workspace — it manages the whole deployment. Treat its credentials accordingly. A workspace admin agent (see Manage agents) governs work inside a single workspace; the Super Admin governs the workspaces themselves.

The Super Admin panel manages the deployment's workspaces from a dedicated Dashboard and Companies view.

Create a workspace

In the Super Admin panel, Companies lists the workspaces and lets you create, edit, or delete them. On Create Company, choose the authentication mode:

• OIDC: enter a name, email domain, and the SSO settings below. Domains help route an email to the right workspace.
• Local accounts: enter a name plus the initial Workspace Admin’s username and email; a display name is optional. No email domain or OIDC provider is required. Create the workspace, then copy the one-time invitation and deliver it privately. The administrator sets their own password and signs in separately.

Local accounts and OIDC are mutually exclusive within a workspace. You cannot convert the authentication mode through workspace editing; local workspaces can be renamed, but their OIDC/domain fields are not editable. Default Auth’s environment-defined account is a separate sign-in option, not the initial local administrator.

Recover the initial invitation

Before the initial administrator accepts an invitation, reopen the local workspace in Companies to reissue, revoke, or replace that invitation. Reissue invalidates the old link; replacement creates a new identity, even if it uses the same username/email. If you revoke it, invite a replacement from the same panel. After any initial-admin invitation has been accepted, this bootstrap recovery closes; ongoing account management belongs to a local Workspace Admin in Workspace users in the sidebar (below Settings), not the Super Admin. See Manage local workspace users.

Choose local accounts to create a workspace and invite its first Workspace Admin without an OIDC provider.

Deleting a workspace is permanent

Deleting a workspace removes it and all of its data — projects, ideas, proposals, tasks, documents, agents, and users. There is no undo.

Configure SSO (OIDC)

These settings apply only to OIDC-mode workspaces. Local workspaces do not expose an OIDC configuration card.

Chorus signs users in through your identity provider using OpenID Connect with PKCE — there is no client secret to manage. You configure it per workspace, in that workspace’s settings in the Super Admin panel, under OIDC Configuration. Two values are required:

• OIDC Issuer URL — your provider’s OpenID Connect discovery URL.
• Client ID — the application’s client ID from your provider.

SSO turns on automatically once both are set; clearing either turns it off. Chorus requests the standard openid profile email scopes.

Choose OIDC at workspace creation and configure the provider. Existing OIDC workspaces can edit these settings later.

At your identity provider, register Chorus as an application and add its redirect (callback) URL to the allowed list: your Chorus site’s address followed by /login/callback. The Companies list shows the exact URL to copy. Because it is built from the address you used to open Chorus, open the Companies page from your production URL and copy the value shown there.

How this reaches your users

Once a workspace has SSO configured, a person signing in with an email on one of its domains is sent to your identity provider and back — the flow described in Account and workspace. A user whose email matches more than one SSO workspace is asked to pick one. Someone already added to a workspace is signed in to it even if their email domain differs.

Next

With workspaces and SSO in place, hand day-to-day setup to each workspace’s operators: Prepare agent access covers creating agent credentials, and Account and workspace covers what your users see when they sign in.