Admin
With Admin installed, staff can see every role and what each may
do, and assign roles to users. Roles themselves are read-only here: they change in nuxt.config.ts and in modules.
Server mode only. Set up the module first: Overview.
Roles pages
| Page | What it shows |
|---|---|
/admin/roles | Every role, with its label, what it is held by (assigned, default or automatic), the roles it inherits, its requirements, user count and permission count. |
/admin/roles/:name | One role: every registered permission, whether the role holds it, and why, from which source (see below). Plus the users who have the role assigned. |
The provenance of each grant says how the role got it:
| Source | Meaning |
|---|---|
host | Your authorization.roles. |
module:<name> | A role shipped by that module with addRole. |
grantTo:<module> | That module put the permission into the role by default (grantTo). |
inherit:<role> | The role inherits it from another one. |
Permissions are marked sensitive (a wildcard never covers them), sessionOnly and implicit (every signed-in user
holds them). A permission can have several sources. An unknown role name on /admin/roles/:name is a 404.
The user roles tab
The "Roles and permissions" tab of /admin/users/:id (needs Widget) shows:
- the roles assigned to the user, with their source:
manual,sso(from single sign-on, read-only here) ormigrated, - their effective roles: assigned, default and automatic ones whose requirements hold, inheritance included,
- the permissions those roles hold.
Staff with roles:assign get an edit button that opens a slideover. It lists the assignable roles. A role is shown
but locked when it holds a permission the staff member does not hold themselves, when it comes from single sign-on, or
when it is auto, default or assignable: false. Saving calls PUT /api/admin/authorization/users/:id/roles, so the
escalation rule applies. A 409 role_not_assignable or 403 shows as a toast.
Who sees it
| What | Needs |
|---|---|
| Roles pages, the tab, and reading a user's roles | roles:read (or roles:assign for a user's roles) |
| Assigning roles | roles:assign, session only |
The admin area itself needs admin:access. Give the permissions to roles in config:
authorization: {
roles: {
admin: { grant: ['*'] }, // roles:read and roles:assign come with *
support: { grant: ['admin:access', 'users:read', 'users:list', 'roles:read'] },
},
}
The menu entry and the tab are hidden for users without roles:read, and the routes check it themselves. Because role
assignment is sessionOnly, an API token or OAuth token can read roles but never change them.
Next steps
- Roles and requirements – what the pages show.
- Users – the permission table and target protection.
- Admin module –
admin:accessand the sidebar.