Roles & permissions
The three roles, what each one unlocks, and how privilege checks behave.
Roles & permissions
The three roles
- user — default. Own work, own settings, own check-ins, chat and gamification.
- admin — everything a user can do, plus member management, role changes and workspace settings.
- superadmin — everything an admin can do, plus the landing-page content manager (/admin/cms) and its audit log.
The canonical list lives in lib/team-settings-model.ts as MEMBER_ROLES. normalizeRole() trims and lowercases input, and isPrivilegedRole() answers the "can this caller govern the workspace?" question used by the API routes.
Becoming a super-admin without the role
ADMIN_EMAILS is an environment variable holding a comma-separated allow-list. A signed-in user whose email is in that list is treated as a super-admin even if their stored role is user. This exists so a first administrator can bootstrap governance before any role has been granted.
What a failed check looks like
- Unauthenticated: 401 with { success: false, message: "Unauthorized" }.
- Authenticated but not privileged: 403 with a message naming the required role. No row is written and no notification is created.
Role changes are audited
PATCH /api/team/members/<id>/role records the previous role, the new role, the actor and the timestamp in team_role_audit. /dashboard/team/settings shows the most recent entries so a promotion can never be silent.
Design guidance
- Grant admin for people-management, not for report access. Reports and exports are available to every signed-in member.
- Keep superadmin to the people who should be able to edit public marketing copy.
- Prefer the ADMIN_EMAILS bootstrap for the first admin, then grant the role in-app and remove the address from the environment if you want the allow-list empty.