Users & Roles

Gatewyse supports a hierarchical multi-tenant user model with role-based access control. This page covers user management, role assignments, the organizational hierarchy, and single sign-on integration.

User Management

User List

The Users page displays a searchable, paginated table with filters for status and role:

Column	Description
Name	The user’s display name
Email	Login email address
Status	`active`, `inactive`, or `suspended`
Roles	Assigned role tags
Last Login	Most recent login timestamp, or “Never”

Use the Status and Role dropdown filters to narrow the list. The search bar matches against name and email.

Creating a User

Click Create User to open the form with these fields:

Name — The user’s full name
Email — Must be unique across the system
Password — Initial password (users can change it after first login)
Role — The role to assign. The canonical role set is the built-in roles listed below plus any custom roles you define on the Roles page. (Note: the current create/filter dropdowns expose a simplified Admin / Manager / User label set; assign finer-grained roles from the user detail page after creation.)

Editing a User

Click Edit to navigate to the user detail page where you can update the user’s name, email, password, role assignments, and status.

User Statuses

Status	Effect
`active`	User can log in and make requests
`inactive`	User account is disabled; login is blocked
`suspended`	User account is temporarily suspended by an administrator

Roles

Roles control what actions a user can perform in the admin dashboard and through the API. The gateway ships with system roles and supports custom role definitions.

Built-in Roles

Role	Scope	Typical Permissions
super-admin	Global	Full access to all tenants and system settings
tenant-admin	Tenant	Manage providers, models, routing, guards, budgets, and users within their tenant
org-admin	Organization	Manage users and budgets within their organization
dept-admin	Department	Manage users and budgets within their department
user	Self	Make API requests within assigned budget limits
read-only	Tenant	View dashboards, usage, and configuration without making changes

Custom Roles

The Roles page (/roles) lets you create custom roles with fine-grained permissions. Each role defines:

Name and slug — Human-readable name and a URL-safe identifier
Description — What the role is intended for
Scope — The organizational level the role applies to
Permissions — A list of resource/action pairs (e.g. providers: [read, write], budgets: [read])
System flag — System roles cannot be deleted or modified

Multi-Tenancy

The gateway organizes users into a three-level hierarchy:

Tenant
  +-- Organization
        +-- Department
              +-- User

Tenants

Tenants are the top-level isolation boundary. Each tenant has its own providers, models, routing rules, guards, budgets, and users. Tenants are managed on the Tenants page (/tenants) and have these properties:

Name and slug
Status — active, suspended, or pending
Plan — The subscription plan (determines feature availability)
Organization count and Department count

Organizations and Departments

Within a tenant, organizations group related departments, and departments group users. These levels provide scoping for:

Budget enforcement (spend limits at each level)
Role-based access (org-admins and dept-admins)
Usage reporting and audit trails

Authentication

Password Authentication

Users log in with email and password. The server issues HttpOnly cookies for session management with automatic token refresh. MFA (multi-factor authentication) is supported — when enabled, the login flow prompts for an MFA code after password verification.

Single Sign-On (SSO)

SSO is configured on the Settings page. The gateway supports two protocols:

OpenID Connect (OIDC)

Configure with:

Issuer URL (e.g. https://accounts.google.com)
Client ID and Client Secret
Scopes (default: openid email profile)

SAML 2.0

Configure with:

IdP SSO URL (entry point)
IdP Entity ID (issuer)
IdP signing certificate (X.509 PEM format)

After SSO is enabled, the login page shows an SSO button. The callback is handled at /auth/sso-callback. User accounts are automatically provisioned on first SSO login.

Multi-Factor Authentication (MFA)

Gatewyse supports TOTP-based multi-factor authentication (compatible with authenticator apps such as Google Authenticator, 1Password, or Authy). Enrollment is a two-step confirm-before-activate flow, so a pending secret never blocks login until the user proves possession of it. All MFA endpoints act on the authenticated user’s own account (/me).

Enrollment

1. Begin setup

POST /api/admin/auth/me/mfa/setup

Generates a pending TOTP secret and returns an otpauth:// URI (render it as a QR code for the authenticator app) plus the base32 secret for manual entry:

{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "otpauthUri": "otpauth://totp/AI%20Gateway:user@example.com?secret=..."
  }
}

The secret stays pending — mfaEnabled remains false and login is unaffected — until the code is confirmed. Setup is rejected if MFA is already enabled; disable it first to re-enroll.

2. Confirm and enable

POST /api/admin/auth/me/mfa/enable
Content-Type: application/json

{ "code": "123456" }

Verifies the code against the pending secret, activates MFA, and returns a set of one-time recovery codes shown exactly once (store them securely; they are the fallback if the authenticator is lost):

{ "data": { "recoveryCodes": ["abcde-fghij", "klmno-pqrst", "..."] } }

Disabling MFA

POST /api/admin/auth/me/mfa/disable
Content-Type: application/json

{ "code": "123456" }

Disabling requires proof of possession — a current TOTP code or an unused recovery code — so a hijacked session cannot silently strip a user’s second factor.

Regenerating recovery codes

POST /api/admin/auth/me/mfa/recovery-codes
Content-Type: application/json

{ "code": "123456" }

Requires a current TOTP or recovery code, invalidates the previous set, and returns a fresh set of codes exactly once.

Once MFA is enabled, the login flow prompts for a code (mfaCode) after the password is verified.

Session Management

Each login establishes a session family backed by a rotating refresh token. Users can review and revoke their own sessions; administrators can force-logout a user tenant-wide.

User self-service

List active sessions

GET /api/admin/auth/me/sessions

Returns the caller’s active sessions, each with its sid, createdAt, lastUsedAt, and (where captured) the originating ip and userAgent. Expired sessions are pruned as they are listed.

Revoke one session

DELETE /api/admin/auth/me/sessions/:sid

Revokes a single session by its sid — useful for signing out a lost or unrecognized device.

Admin force-logout

An administrator can revoke all of a user’s sessions at once (tenant-scoped — only for users within the admin’s own tenant):

POST /api/admin/users/:id/revoke-sessions

Requires the users:update permission and returns the count of sessions revoked.

Refresh-token rotation and reuse detection

Refresh tokens are rotated on every use and tracked per session family. If a rotated-out (already-superseded) refresh token is ever presented again, that is treated as token theft: the entire session family is revoked, not just the replayed token. The replay is logged and the request is rejected.