UserRole enum in src/common/models.py and the gates in src/common/auth.py and src/apis/simulation_admin/access.py.
Canonical role values (API)
Role strings appear on authenticated API requests (for example as claims on issued tokens, depending on your deployment). Typical meanings:| Role | Value in API | Typical use |
|---|---|---|
| Super admin | super_admin | Cross-org platform operations, elevated admin APIs. |
| Organization admin | admin | Full org admin UI and /api/v1/admin/simulation/* (with org scope). |
| HR | hr | Org-scoped people tasks; not simulation admin API. |
| Executive | executive | Learner-class experience; current Next.js gates for chat vs admin dashboard treat executive like employee (no redirect to /admin or /org-admin). Individual API routes may still check this role when added. |
| Employee | employee | Default learner. |
| Bot | bot | AI characters and automated identities—not org admins. |
super_admin as satisfying elevated checks even when the primary role would be admin or stricter.
Organization admin vs HR (important distinction)
adminis role that passesrequire_adminon simulation admin routes (src/apis/simulation_admin/access.py). Those routes implement simulation settings, characters, tasks, templates, knowledge, replay, and related org configuration.hrcan help with people workflows (for example creatingemployeeusers via the users API—seesrc/apis/users.py) and can access certain frontend pages thatadmincan also access (for example/characters).hrdoes not receive org admin dashboard access or simulation admin API access underrequire_admin.
admin role unless stated otherwise—not hr.
Main frontend routes by role
| Surface | Route(s) | Who uses it |
|---|---|---|
| Learner hub (chat) | /chat | employee, executive, hr (and others who are not steered away—see below). Primary Slack-like experience: channels, DMs, tasks, lifecycle polling, notifications. |
| Personal dashboard | /dashboard | Learners; personal metrics and insights. |
| Org admin dashboard | /org-admin for org admins, /admin for platform admins | admin, super_admin. Org admins are placed in organization view for their tenant; super admins can switch to platform view. |
| Characters lab | /characters | admin and hr only (product UI gate). |
| Onboarding | /onboarding/* | New users moving through signup and profile flows. |
admin or super_admin to admin surfaces (/org-admin for org admins, /admin for super admins) instead of keeping them on /chat. So in current product, org and platform admins are not positioned as primary “chat learners” on first entry—design and docs should assume they manage from admin dashboard surfaces unless routing changes.
Org admin dashboard (role admin)
Rendered via OrgDashboard (frontend/src/features/org-admin/components/). Typical areas:
| Area | Purpose |
|---|---|
| Overview | Organization health, simulation health, team performance, members. |
| People | Member-oriented admin for the org. |
| Analytics | Org-level analytics and simulation KPIs where wired. |
| Simulation | SimulationDashboard — characters, tasks, templates, settings, scenario tooling, knowledge uploads, replay, and other simulation admin features backed by /api/v1/admin/simulation. |
| Settings | Branding and org-facing settings exposed by the product. |
Platform super admin (role super_admin)
Same /admin shell with platform tabs (for example users, organizations, analytics, billing, system health, audit logs)—see AdminSidebar and related components. Uses cross-org and /api/v1/admin/... style endpoints where implemented.
API enforcement (summary)
| Pattern | Meaning |
|---|---|
require_admin | Only admin or super_admin. Used across /api/v1/admin/simulation/*. |
require_roles([ADMIN, HR]) | Example: creating users in-org; HR may create employee users only (see users API). |
require_super_admin | Platform-only routes. |
| Org id on requests | Non–super-admin callers are generally restricted to current_user.organization_id for mutating org data. |
Related documentation
- Architecture overview — System layers and tenancy.
- Organization admin manual — Simulation configuration entry point.
- Permissions and roles — Short matrix; this page is the detailed map.
- Frontend overview, Admin panels — UI conventions.
Source anchors
- Roles:
src/common/models.py(UserRole). require_admin:src/apis/simulation_admin/access.py.- Chat redirect:
frontend/src/app/chat/page.tsx. - Admin dashboard gates:
frontend/src/app/admin/page.tsx,frontend/src/app/org-admin/page.tsx. /charactersgate:frontend/src/app/characters/page.tsx.