Manage admins & roles

Prerequisites

• Role with admins:write (superadmin) for user CRUD.
• Role with roles:manage (superadmin) for role editor.

Admin identity and role editing are superadmin-only. Both surfaces write audit entries.

Admin users

System → Admins (/system/admins).

Create

• Email: used for login.
• Name: display.
• Role: pick from the 6 built-in or any custom role.
• Password: temporary; user must reset on first login.

Edit

• Rename, reassign role, disable/re-enable.
• Changing role requires the user to re-login (bumps token_version).

Disable vs delete

• Disable: sets is_active=false. Logins refused with admin_disabled. Reversible.
• Delete: soft-delete; row remains for audit trail. Not recommended unless the admin left the company permanently.

Force logout

The “Force logout” action on an admin bumps their token_version. Every issued JWT for that admin becomes invalid on next request.

Roles

System → Roles (/system/roles).

The 6 built-in roles

superadmin, content_manager, moderator, support, analyst, finance. Marked is_system=true. Cannot be deleted. Can be edited only to add permissions: you can’t remove baseline permissions from a system role (a safety rail).

Custom roles

Create with:

• Name: unique, cannot collide with system role names.
• Description: what this role is for.
• Permissions: checkboxes from the permission groups (matches the Permissions matrix).

Role editor UI

Permissions are grouped by resource:

• Catalog, Publishing, Curation, Users, Wallet, Payments, Pricing, Moderation, Push, Analytics, System.

Each group can be expanded to see per-action perms. The editor prevents obvious foot-guns (e.g. granting wallet:adjust without wallet:read).

Deleting a custom role

• Requires no admins to be assigned to it. The delete modal walks you through reassignment.
• Deleting a role goes through the approvals queue (two-person rule).

Audit

Every admin CRUD and role edit writes to AuditLog:

• action='admin.create|update|delete|disable|enable'
• action='role.create|update|delete'
• before/after includes the permission arrays for role changes: grep-able for compliance.

Gotchas

• The last superadmin cannot be disabled. Enforced server-side to prevent lockout.
• Editing your own admin row is allowed but audited. Do not lower your own permissions in a way that locks you out.
• Custom role deletion goes through approvals: plan ahead.

API calls

Action	Endpoint
List admins	GET /v1/admin/admins
Detail	GET /v1/admin/admins/:id
Get self	GET /v1/admin/admins/me
Create	POST /v1/admin/admins
Update	PUT /v1/admin/admins/:id
Delete	DELETE /v1/admin/admins/:id
List roles	GET /v1/admin/roles
Detail role	GET /v1/admin/roles/:id
Create role	POST /v1/admin/roles
Update role	PUT /v1/admin/roles/:id
Delete role	DELETE /v1/admin/roles/:id

Full details in API: System.