> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles & Permissions (RBAC)

> 5-role hierarchy, org vs community scope, per-user tokens, read-only Viewer patterns

Nudj has a 5-role hierarchy, enforced at both client and server layers. Roles can be org-level (see every community) or community-scoped (see one specific community).

## The 5 roles

| Level | Role           | Short summary                                                                                                                |
| ----- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 0     | **Viewer**     | Read-only access to all subjects. Default for new invites. Good for analytics reviewers, external stakeholders.              |
| 1     | **Moderator**  | Manage Comments, Posts, Users (moderation). Read-only on everything else. Good for community managers.                       |
| 2     | **Manager**    | Full CRUD on content (Challenges, Actions, Rewards, Posts, etc). Read-only on Users, Org, Config. Good for content creators. |
| 3     | **Admin**      | Full org management. Manage Users, Config, everything except delete Org. Good for admins.                                    |
| 4     | **SuperAdmin** | God mode. Full CRUD on all subjects. Rarely needed outside platform-level ops.                                               |

<Note>
  **Moderator** is new (#1865). The old **Creator** role was renamed to **Manager**, and **Analytics** was renamed to **Viewer**.
</Note>

***

## Role scope

Role strings encode scope:

```text theme={null}
orgId-{id}:role-{role}                    ← org-level: sees every community
orgId-{id}:comId-{id}:role-{role}         ← community-scoped: sees one community only
role-super-admin                           ← global SuperAdmin: bypasses all checks
```

Community scope limits what that member sees in dashboards, user lists, analytics. Org-level roles see everything.

***

## Permission matrix

Permissions are `action + subject` pairs (`can-update:subject-Challenge`, etc). The 5 CRUD actions are:

* `create`, `read`, `update`, `delete`, `manage` (= all four).

Subjects: `Challenge, Action, Reward, Post, Achievement, User, Organisation, PlatformConfig, LeaderboardConfig, Team, AuthAccount, ...`

Each role has an explicit allow/deny list. See `packages/models/util/rbac/config/role-permissions.config.ts` in the codebase for the source of truth.

***

## Per-user access tokens

Each team member has a **personal access token** (#1816, #2352) for API calls and scripted automation. The token carries the member's roles in its JWT payload — the API derives permissions from there.

### Revoking tokens

Admin+ can revoke any member's token via **Settings -> Team Members -> member -> Revoke Token**, or via the Admin API `/tokens/revoke` endpoint. Revocation is immediate.

***

## Client-side RBAC

The admin UI hides controls the member can't use (#1864):

* Buttons and menu items filter by permission.
* Nav entries don't appear for unreadable subjects.
* Edit pages wrap form content in `<ReadOnlyFieldset>` — Viewers see the content but can't edit.

This is **UX**, not security. Server-side enforcement is authoritative.

***

## Server-side enforcement

Every API call validates the calling token's roles against the requested action+subject (#1875). Mismatched calls get a 403. Client-side restriction alone is insufficient — we enforce on both ends.

***

## Assigning roles

Only **Admin+ (org-scoped)** or **global SuperAdmin** can assign roles. Members can assign roles **at or below their own level** — an Admin can assign Admin, Manager, Moderator, Viewer; they cannot assign SuperAdmin.

Community-scoped Admin roles cannot assign roles at all — only org-level Admins can.

See [Team Members](/admin-guide/settings/team-members) for the invite flow.

***

## ReadOnlyFieldset (the Viewer pattern)

Edit pages use a `<ReadOnlyFieldset>` wrapper. For Viewer and Moderator roles:

* All form inputs disabled.
* A "View only" banner appears at the top of the edit area.
* Navigation stays enabled so Viewers can explore.
* Save / delete / status-change buttons hide automatically.

This pattern is applied to:

* Challenge edit, Achievement edit, Post edit, Reward edit
* Leaderboard edit, Game config edit, Streak edit
* Organisation settings, Community settings

***

## Super-admin gated items

Some platform-level items are **SuperAdmin only** (#926) — e.g. default templates that ship with new communities. Regular Admins can use them but can't edit the master templates.

***

## Invite-button permissions

The **Invite** button on the Team Members page requires `update` permission on the Team subject (#1946). Moderators and below can't invite; Managers and above can.

***

## Custom roles?

Nudj doesn't support custom roles (e.g. "CustomerSupport" with a bespoke permission set). The 5 built-in roles + org/community scope cover the vast majority of use cases. If you need more granularity, contact support.

***

## Best practices

<Tip>
  Default new team members to **Viewer**, then upgrade after you've confirmed their role. Easier than explaining why you removed permissions.
</Tip>

<Tip>
  For multi-community orgs, use **community-scoped roles** liberally — one community's manager shouldn't see another's private analytics.
</Tip>

<Warning>
  **SuperAdmin is rare**. Use it sparingly — typically only platform ops or the founding admin. Every SuperAdmin is a potential blast radius.
</Warning>