Skip to content

Users And Roles

Every user has one of three hierarchical roles:

Role Description
user Standard user with basic access. Default role for new accounts.
admin Administrator with access to user management features.
super_admin Full control over all users and roles.
super_admin
│
▼
admin
│
▼
user
  1. A user authenticates via the configured provider (see Identity Integration).
  2. On first login, a user record is created with role user.
  3. The profile (email, name, avatar) is synced from the provider.
  4. Subsequent logins update the profile and increment a login counter.
Middleware Required Role Description
requireJWT Any authenticated Validates the session JWT
requireAuth Any authenticated Ensures the user is synced and active
requireAdmin admin or super_admin Access to admin endpoints
requireSuperAdmin super_admin only Reserved for super-admin-only operations

All endpoints below require admin or super_admin.

Endpoint Method Description
/v1/admin/users GET List all users (paginated)
/v1/admin/users/:id GET Get user details
/v1/admin/users/:id PATCH Update user
/v1/admin/users/:id DELETE Soft delete user
/v1/admin/users/:id/activate POST Activate user
/v1/admin/users/:id/deactivate POST Deactivate user
Action Who Can Perform
Promote user to admin super_admin only
Promote user to super_admin super_admin only
Demote admin to user admin or super_admin
Demote super_admin to any role super_admin only
Modify own role Not allowed, regardless of role

Only super_admin can create other admins or demote another super_admin — a regular admin cannot do either. No user, at any role, can change their own role, which prevents both accidental self-demotion and self-escalation.

Action Who Can Perform Self-Action Allowed
Deactivate user admin or super_admin No
Deactivate admin admin or super_admin No
Deactivate super_admin super_admin only No
Activate a user admin or super_admin N/A
Delete a user admin or super_admin No

No user can deactivate or delete their own account. Only super_admin can deactivate another super_admin. Deletion is a soft delete — it sets deleted_at and the record is preserved but excluded from queries; deactivated users (is_active = false) are blocked at the requireAuth middleware with a 403 Forbidden.

Field Type Description
id UUID Primary key
auth0_id string External identity subject (Auth0 or WorkOS)
email string Synced from the identity provider
name string Synced from the identity provider
avatar_url string Synced from the identity provider
role enum user, admin, or super_admin
is_active boolean Account active status
last_login_at timestamp Last login time
login_count integer Total login count
metadata jsonb Custom, extensible metadata
created_at / updated_at timestamp Record timestamps
deleted_at timestamp Soft-delete timestamp, null if not deleted

A later migration introduced organizations and organization_members tables. This changes where role authority actually lives:

  • users.role (the three-role model above) is deprecated in favor of organization_members.role — role now applies per organization membership rather than globally to the user record.
  • users.is_platform_admin gates cross-tenant actions — operations that reach across organizations rather than acting inside one.

The role hierarchy and business rules above still apply in shape (a user/admin/super_admin ladder with the same promotion/self-modification restrictions), but on a multi-tenant deployment a user’s effective role is scoped to their membership in a specific organization rather than being a single global value.