Roles & Permissions

UniAuth uses role-based access control (RBAC) to govern what each user can see and do across the platform. Every user is assigned a single role, and that role carries a set of granular permissions that determine access to admin features, API endpoints, and protected resources.

Overview

UniAuth ships with three built-in roles that cover the most common access patterns. Administrators can also create custom roles with tailored permission sets to match their organization's needs. Roles are stored in the roles table and referenced by name in each user record.

Built-in Roles

Role	Description	Access Level
admin	Full system access	Can manage all users, roles, sessions, OAuth clients, webhooks, analytics, and system settings. Can impersonate users and rotate OIDC keys.
moderator	Read-only management access	Can view users, sessions, activity logs, and dashboard statistics. Cannot modify accounts, change roles, or manage OAuth clients.
user	Standard user (default)	Self-service access only. Can manage their own profile, security settings, connected services, and register OAuth applications via the developer console.

Built-in roles are marked as system roles and cannot be deleted. However, administrators can modify their permission sets if the defaults do not fit their requirements.

Organization roles

The roles above are platform roles — they live on the user record and govern the admin console. Organization membership is a separate axis: when a user belongs to a team, their organization_members row carries a per-organization role that applies only inside that org:

Org role	Scope within the organization
owner	Created the org or was given ownership. Full control: billing, domains, SSO/SCIM, members — and can delete the org.
admin	Runs the org day-to-day: members, groups, OAuth clients, and (on Enterprise) domains, SSO and SCIM tokens. Cannot delete the org.
member	Belongs to the org and appears in its groups claim, but has no org-admin access.

Organization roles are enforced by verifyOrgRole, separate from the platform middleware. An owner or admin manages them from the team admin area at /org/<id>/admin/users — no platform-admin role is required. The same membership also appears in the OIDC groups claim as org:<slug>:<role> (see the Groups & RBAC guide).

Permissions

Permissions are stored as a JSON array on each role and follow a resource:action naming convention. The complete list of available permissions:

Permission	Description	Admin	Moderator
`users:read`	View user list and details	Yes	Yes
`users:write`	Modify user accounts (change role, lock/unlock)	Yes	No
`users:delete`	Delete user accounts	Yes	No
`sessions:read`	View active sessions	Yes	Yes
`sessions:revoke`	Revoke any user's sessions	Yes	No
`logs:read`	View activity and audit logs	Yes	Yes
`roles:read`	View roles and their permissions	Yes	No
`roles:write`	Create, modify, and delete custom roles	Yes	No
`stats:read`	View dashboard statistics and analytics	Yes	Yes
`settings:read`	View system configuration	Yes	No
`settings:write`	Modify system settings (SMTP, branding, policies)	Yes	No
`oauth:read`	View all registered OAuth clients	Yes	No
`oauth:write`	Create, modify, and delete OAuth clients	Yes	No

Role in JWT Tokens

The user's role is embedded in their session JWT, making it available for server-side authorization checks without additional database queries. The JWT payload includes:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "admin@example.com",
  "firstName": "Jane",
  "lastName": "Admin",
  "role": "admin",
  "iat": 1700000000,
  "exp": 1700604800
}

This allows your application code or middleware to make authorization decisions based on the role claim without hitting the database on every request.

Middleware Protection

All routes under /admin/* are automatically protected by the UniAuth middleware. The middleware performs two checks:

Authentication — The request must include a valid session cookie. Unauthenticated requests are redirected to the login page.
Role check — The user's role (from the JWT) must be admin or moderator. Users with insufficient permissions receive a 403 response.

This protection runs at the edge before your page or API handler executes, so unauthorized requests are blocked with minimal latency.

API Role Checks

In addition to middleware-level protection, individual API route handlers verify the caller's role using the verifyAdmin() helper function. This provides defense in depth:

// Example: Admin API route handler
import { verifyAdmin } from "@/lib/admin";
import { successResponse, errorResponse } from "@/lib/api-response";

export async function GET(request: Request) {
  // verifyAdmin() checks the session cookie and confirms
  // the user has admin or moderator role
  const adminUser = await verifyAdmin();
  if (!adminUser) {
    return errorResponse("Unauthorized", 403);
  }

  // Proceed with admin-only logic
  const data = await fetchSensitiveData();
  return successResponse(data);
}

For more granular checks, you can inspect the user's specific permissions by loading the role from the database and checking the permissions array.