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 │ ▼ userAuthentication Flow
Section titled “Authentication Flow”- A user authenticates via the configured provider (see Identity Integration).
- On first login, a user record is created with role
user. - The profile (email, name, avatar) is synced from the provider.
- Subsequent logins update the profile and increment a login counter.
Access Control Middleware
Section titled “Access Control Middleware”| 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 |
Admin Endpoints
Section titled “Admin Endpoints”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 |
Business Rules
Section titled “Business Rules”Role Modification
Section titled “Role Modification”| 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.
Account Management
Section titled “Account Management”| 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.
User Data Model
Section titled “User Data Model”| 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 |
Multi-Tenant Organizations
Section titled “Multi-Tenant Organizations”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 oforganization_members.role— role now applies per organization membership rather than globally to the user record.users.is_platform_admingates 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.