Skip to Content
User GuideUsers, roles & access

Users, roles & access (step-by-step)

This guide describes how access works in the Tenant Plane (TP) and what you can do in the UI today. TP users are separate from Control Plane users (platform operators).

1. Who uses what

SurfaceWhoURL pattern
Tenant PlaneYour company’s employees: operators, requesters, fulfillershttps://<tenant-slug>.<domain> (or dedicated endpoint_url)
Self-service portalSame TP login; requesters live mostly on /portal.../portal
Control PlaneSaaS / platform staff (tenants, billing)Separate CP host (e.g. cp.<domain>)

2. Step-by-step: sign in (first time)

  1. Open the tenant URL from your welcome email (or internal runbook).
  2. Complete set password if you received an invite or signup token link.
  3. Or use SSO (Sign in with SSO) if configured.
  4. After login, the app stores a session (Bearer token and/or atlas_token cookie, depending on deployment).

First user on an empty tenant (rare in production): POST /api/auth/register may create the first admin only when no users exist. If users already exist, registration returns 403 — use invite or SSO instead.

3. Step-by-step: invite a colleague (admin)

  1. Sign in as a user with users:write or rbac:manage (typically admin).
  2. Open Settings → jump to Users & access (or scroll to that card).
  3. Enter the colleague’s email under Invite user and click Send invite.
  4. The system calls POST /api/auth/invite, which creates a signup JWT and emails a link (or shows a link if mail is not configured).
  5. The invitee opens the link → /auth/callback → signup-exchange with password.

Important (current product behavior): completing signup-exchange assigns the admin role in the default path. For requester / fulfiller / operator at scale, prefer SSO with group → role mapping or SCIM (below) rather than relying on invite alone for least privilege.

4. Step-by-step: deactivate a user

  1. Settings → Users & access.
  2. Find the user and click Deactivate (or Activate to restore).
  3. This uses PATCH /api/users/[id] with active: false. The user cannot sign in; audit history remains.

5. Roles and what they do

Built-in roles are ensured in the TP user store (e.g. ensureAdminRole, ensureOperatorRole, ensureFulfillerRole, ensureRequesterRole).

RoleTypical permissions / scopeDefault experience
admin* (full TP)All modules + Settings, user invite, RBAC editor
operatorIncidents, tickets, runbooks, automation read, ITSM read/write, CMDB read, etc.Full ops workspace
fulfillerService desk: ITSM, incidents, tickets, changes, KEDBPortal + ITSM / Incidents links
requesteritsm:read, itsm:write (portal-focused)Portal catalog, requests, knowledge — no incident shortcut in portal header

Navigation and landing paths are filtered by effective role (see shared ROLE_NAV_CONFIGS). /api/me exposes role and permissions for the UI.

6. Step-by-step: SSO and group → role (enterprise)

  1. As admin, configure SSO (SAML / OIDC) if your deployment exposes it (Settings or /api/auth/sso-config).
  2. Set global mapping (environment), e.g. SSO_GROUP_ROLE_MAP=Helpdesk:fulfiller,Employees:requester.
  3. Or set per-tenant group_role_map on POST /api/auth/sso-config, e.g. { "IdP-Helpdesk": "fulfiller", "IdP-AllStaff": "requester" }.
  4. Ensure your IdP sends groups in tokens or SAML attributes.
  5. On first SSO login, JIT creates the user and assigns a role from groups; if no group matches, env SSO_JIT_DEFAULT_ROLE / tenant jit_default_role applies (else operator in code paths — confirm with your deployment).

7. Step-by-step: SCIM (optional)

If SCIM is enabled, your IdP provisions users and group membership against /api/scim/v2/*. Groups map to TP roles; membership updates assignments. Use SCIM when you need centralized lifecycle (joiner/mover/leaver) and role from directory groups.

8. Permissions and APIs

  • Flat permissions (e.g. users:read, rbac:manage) gate list users (GET /api/users), invite, and many routes via requirePermission.
  • Scoped checks (e.g. itsm, read/write) gate ITSM catalog and requests.
  • Settings → Roles & permissions (RBAC) includes effective permissions for the current user, “can I?” (/api/rbac/can-i), and a permission editor for scoped role permissions (by role ID) via /api/rbac/role-permissions.

Note: The Settings UI does not currently offer a simple dropdown to change an existing user’s role; use SSO groups or SCIM for role changes at scale, or operational procedures aligned with your deployment.

9. Shared / demo anonymous access

Some demo deployments set TP_SHARED_ANONYMOUS_ACCESS=1, which injects a read-only synthetic principal for many GETs — not a substitute for real user RBAC. Turn off for production customer tenants.

10. Quick reference

TaskSteps
Add user (password)Settings → Invite → share link → invitee sets password
Add user (SSO)Map IdP groups → roles; user signs in with SSO
Portal-only employeeAssign requester (SSO group or SCIM)
Service deskAssign fulfiller or operator
Full adminadmin role (break-glass IdP group)

See also

OverviewSelf-service portal