Multi-Tenancy and Authorization

Ragty separates platform administration, tenant permissions, and workspace permissions. These scopes are independent and must not be treated as one role hierarchy.

Authorization Scopes

Scope	Values	Meaning
Platform	`superadmin`	Installation-wide user and tenant administration
Tenant	`admin`, `editor`, `dataset_editor`, `normal`, `chat`	Permissions inside one tenant
Workspace	`owner`, `editor`, `viewer`	Permissions inside one workspace

Tenant ownership is stored separately in tenants.owner_user_id. Ownership protects the owner from removal or demotion but does not replace tenant RBAC. The owner normally also has tenant role admin.

Platform Superadmin

Only a platform superadmin can:

List and administer all platform users
List, create, delete, and transfer ownership of tenants
Grant or revoke the tenant admin role
Configure provider credentials and default models
Use platform administration screens

A tenant administrator or tenant owner is never implicitly a platform superadmin. Platform authority is read from the active user record, not only from a potentially stale JWT claim.

Tenant Roles

Roles are ordered by privilege: admin > editor > dataset_editor > normal > chat. The chat role is the least-privileged tenant membership.

Permission	admin	editor	dataset_editor	normal	chat
Rename tenant	✅	❌	❌	❌	❌
Invite/remove members and manage lower roles	✅	❌	❌	❌	❌
Create/delete groups and manage group members	✅	❌	❌	❌	❌
Assign datasets to users/groups	✅	❌	❌	❌	❌
Configure API keys and security settings	✅	✅	✅	✅	❌
Create/edit/delete any tenant dataset	✅	✅	❌	❌	❌
Create/edit/delete assigned datasets	✅	✅	✅	❌	❌
Upload/delete documents in any tenant dataset	✅	✅	❌	❌	❌
Upload/delete documents in assigned datasets	✅	✅	✅	❌	❌
Create/edit/delete dialogs	✅	✅	❌	✅	❌
Use chat	✅	✅	✅	✅	✅

The chat role can only use chat. It is explicitly rejected from dialog, configuration, and API-key mutations (require_not_chat_only), so it cannot manage providers, security settings, or API keys. The frontend hides every non-chat navigation item and the dialog create, edit, and delete controls; backend authorization remains authoritative for direct requests.

The normal role remains a legacy general member role. It can currently create, edit, and delete dialogs, and a workspace owner or editor can also receive additive dataset and document management rights. This is why normal is kept separate from the deliberately restricted chat role.

Provider configuration is tenant-owned data but is administered only by the platform superadmin. Tenant admins can use providers already configured for their tenant.

Workspace Roles

Workspace permissions are additive to tenant permissions:

Workspace role	Permissions
`owner`	Rename/delete the workspace, manage members, and manage its datasets, dialogs, and documents
`editor`	Manage the workspace's datasets, dialogs, and documents
`viewer`	Read content made available through the workspace

A workspace owner or editor can manage resources in that workspace even when their tenant role is normal; this workspace exception does not apply to the chat role. Tenant admin and editor retain tenant-wide dataset permissions. Caller-supplied workspace, dataset, dialog, and document IDs are still validated against the active tenant.

Dataset Visibility

Tenant admin and editor see all datasets in the active tenant.
Tenant dataset_editor sees datasets assigned directly or through a group.
Tenant normal has no tenant-level dataset access, but may receive additive read or management rights through a workspace role.
Tenant chat has no dataset or document management access, even through a workspace role; it can only use accessible chat resources.
Search always applies tenant and dataset filters at execution time.

Registration

Self-registration is disabled platform-wide by default. Enable it with M8TY_RAGTY_SELF_REGISTRATION_ENABLED=true. The platform default tenant then controls admission:

Mode	Result
`open`	Creates an active `normal` tenant membership and personal workspace
`approval`	Creates a pending registration request; no active session yet
`closed`	Rejects self-registration

Self-registration never creates a tenant or grants tenant/platform administration. OIDC just-in-time provisioning is a separate switch: M8TY_RAGTY_OIDC_AUTO_PROVISION_ENABLED=true.

Authentication Modes

Mode	Description
`local`	Local email/password authentication with an HS256 JWT (default)
`oidc`	External OIDC provider with JWKS verification
`both`	Try local JWT verification, then OIDC

Configure M8TY_RAGTY_AUTH_MODE. OIDC modes require M8TY_RAGTY_OIDC_ISSUER_URL; the audience defaults to m8ty-rag through M8TY_RAGTY_OIDC_AUDIENCE.

Bootstrap and Migration

A first-start platform superadmin can be created on an empty database with:

M8TY_RAGTY_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
M8TY_RAGTY_BOOTSTRAP_ADMIN_PASSWORD='at-least-12-characters'
M8TY_RAGTY_BOOTSTRAP_ADMIN_NAME=superadmin

Bootstrap requires local or both authentication and creates the initial Default Tenant. Tenant ownership and legacy role migrations run automatically at backend startup. The idempotent operational command remains available:

cd backend
uv run python scripts/migrate_tenants.py

12 September 2026