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 — One of user, manager, or admin

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

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.