Managing Platform Users

Platform access and tenant access are two independent scopes on the same NestAuthUser row. The admin console surfaces both, side by side, so you can tell a super-admin apart from a tenant user and manage their roles without dropping into code.

See User Access & Platform Access for the conceptual split; this page covers the console.

The two scopes

A user's platformAccess marker is what makes them a platform user — a tenant-less userAccess alone does not. This is the same marker the login path enforces.

A user can hold both. Nothing couples the two scopes — the same account can be a platform super-admin and a member of several tenants, each with its own roles. Which scope applies is decided per login, by your platformAccess.validate(request), not by the user record: a platform login resolves platformAccess.roles, a tenant login resolves that tenant's userAccess.roles. The two never merge into one session.

Finding platform users

The Users list has an Access scope filter (shown when platformAccess.enabled is true):

Platform users carry a Platform chip next to their email, and their platform roles render separately from tenant roles so a super-admin can never be mistaken for someone with a tenant role of the same name.

The same filter is available on the API:

GET /auth/admin/api/users?scope=platform
GET /auth/admin/api/users?scope=tenant
GET /auth/admin/api/users?scope=all      # default

It composes with the existing search, status, tenantId, and roleName filters, and the response meta.scope echoes the resolved value. Every user payload now includes platformAccess (or null) plus an isPlatformUser convenience flag.

Assigning platform roles

Open a user and use Platform Access → Manage roles. Only global (tenant-less) roles are eligible — a platform role applies everywhere, so a tenant-scoped role would be meaningless there. The user must already hold platform access (see below).

Via the API, PATCH the user with platformRoleIds:

PATCH /auth/admin/api/users/:id
Content-Type: application/json
 
{ "platformRoleIds": ["<global-role-id>"] }

This replaces the platform roles wholesale (send [] to clear them) and never touches tenant roles — those stay under tenantRoles.

Granting and revoking platform access

There are two ways to make someone a platform user from the console:

1. On an existing user — open them and click Platform Access → Grant access. Their tenant memberships and tenant roles are untouched.
2. At creation — tick Platform user (super-admin) in the Create User dialog. That provisions a tenant-less account with the marker in one step; tenant selection is skipped (you can add tenants afterwards).

Revoke removes the marker and, with it, that user's platform roles. Tenant access is unaffected — the user simply stops being a platform user.

On the API, both are the same field:

PATCH /auth/admin/api/users/:id   { "isPlatformUser": true }   # grant
PATCH /auth/admin/api/users/:id   { "isPlatformUser": false }  # revoke
POST  /auth/admin/api/users       { "email": "…", "isPlatformUser": true }

Granting is idempotent, and isPlatformUser is applied before platformRoleIds, so one request can grant access and set roles together:

PATCH /auth/admin/api/users/:id
{ "isPlatformUser": true, "platformRoleIds": ["<global-role-id>"] }

Assigning platformRoleIds to a user who holds no platform access is still refused with 400 NOT_PLATFORM_USER — grant it first (or in the same request).

This is a privilege-escalation surface. Any console admin can make any user — including themselves — a platform super-admin. The only gate is platformAccess.enabled: with it unset or false, both grant and platform-user creation are refused with 400 PLATFORM_ACCESS_DISABLED, and the UI hides the controls entirely. Restrict who can reach the admin console accordingly.

Provisioning from application code still works and is the right choice for bootstrapping the first super-admin, where there's no console session yet:

// Bootstrap / seeder.
let user = await this.users.getPlatformUserByEmail(email);
if (!user) {
  user = await this.users.createPlatformUser({ email, isActive: true });
}
const access = await user.getPlatformAccess(true);
await access.assignRoles([role.id]);

See the platform-admin portal recipe for a full walkthrough, and UserService for createPlatformUser, getPlatformUserByEmail, getPlatformUsers, and getPlatformUsersByRole.

Multiple tenants alongside platform access

Granting a platform user tenant memberships is the ordinary tenant flow — the Tenants section on the same detail page:

• SHARED mode — Add tenant assigns as many tenants as you need; each card carries its own roles.
• ISOLATED mode — one tenant per user, assigned at creation.

Because the scopes are independent, adding or removing tenants never affects platform roles, and vice versa.