Admin UI Authentication

The Admin UI uses session-based authentication with support for multi-factor authentication (MFA), role-based access control (RBAC), and a user invite system.

Navigate to the Admin UI

Open http://localhost:5173. If not authenticated, you're redirected to /login.

Enter credentials

Enter your email and password. The UI calls POST /api/auth/login.

MFA challenge (if enabled)

If MFA is enabled on your account, you'll see a TOTP code prompt. Enter the 6-digit code from your authenticator app.

Session created

On success, a session token is stored in localStorage and attached to all subsequent API requests via the Authorization header.

First-Time Setup

When no users exist in the system, the UI redirects to /setup:

Enter your name, email, and password
The system creates the first admin account with super_admin role
You're automatically logged in

Warning

The setup endpoint is only available when the database has zero users. After the first admin is created, it returns 403.

Session Management

Sessions are stored in PostgreSQL with the user ID, token, and expiration
Session tokens are automatically attached to every API request
Logout invalidates the session server-side
Expired sessions redirect to the login page

Role-Based Access Control

Four built-in roles with hierarchical permissions:

Role	Topics	Schemas	Mappings	Webhooks	Users	Keys
super_admin	CRUD	CRUD	CRUD	CRUD	CRUD	CRUD
admin	CRUD	CRUD	CRUD	CRUD	CRUD	Read
editor	CRUD	CRUD	CRUD	CRUD	Read	—
viewer	Read	Read	Read	Read	—	—

Custom Roles

Create custom roles with granular permissions via the Roles page (/roles). The permission matrix lets you check/uncheck specific resource × action combinations.

Permission Resources

topics, schemas, mappings, webhooks
users, roles, invites
keys, deployments
debugger, documents, socket

Permission Actions

read, create, update, delete

Multi-Factor Authentication (MFA)

MFA uses TOTP (Time-based One-Time Password) compatible with Google Authenticator, Authy, 1Password, etc.

Setting Up MFA

Go to your user profile or have an admin navigate to Security → Users
Click Setup MFA
Scan the QR code with your authenticator app
Enter the 6-digit verification code to confirm
MFA is now active on your account

Disabling MFA

Admins can disable MFA for any user via the Users page. Users can also disable their own MFA through the profile settings.

Invite System

Admins can invite new users via email:

Create invite

Go to Security → Invites and click Create Invite. Enter the email address and select a role.

Share the link

Copy the generated invite link and send it to the new user.

Accept invite

The recipient opens the link, sets their name and password, and their account is created with the assigned role.

Invite Statuses

Status	Description
`pending`	Invite sent, not yet accepted
`accepted`	User created their account
`revoked`	Admin revoked the invite
`expired`	Invite link expired

Password Reset

Click Forgot Password on the login page
Enter your email address
A reset token is generated (in production, this would be emailed)
Use the reset link to set a new password