Skip to content
JiraVision

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.