RBAC Permissions

Configure platform admin roles and permissions with defineAdminRBACConfig, and check them safely in the browser and on the server.

Platform admin roles (who can manage users, sessions and the admin panel) are configured in packages/rbac/src/admin-rbac.config.ts with defineAdminRBACConfig. They run on the same engine as organization roles, with one different rule: a role with explicit permissions gets exactly those, and only admin gets everything by default.

Two Namespaces, One Word

Admin roles and organization roles are separate:

Organization rolesAdmin roles
Stored onmember.role (per organization)user.role (per account)
Configured inrbac.config.tsadmin-rbac.config.ts
Imported from@kit/rbac@kit/rbac/admin, @kit/rbac/admin/client

Both contain a role called admin. An organization admin is not a platform admin. Always check admin access with the user's user.role, never a member.role.

Defaults

With defineAdminRBACConfig({}) there is one role, admin (level 100), with every statement:

ResourceActions
usercreate, list, get, update, set-role, set-password, set-email, ban, impersonate, delete
sessionlist, revoke, delete
organizationslist, view
dashboardview
auditlist
outboxlist, get, replay, cancel

user and session and their actions are Better Auth admin plugin names: keep them exact. ban covers unban too. impersonate-admins isn't included, as in Better Auth's own defaults. When Better Auth's admin plugin gets adminRoles: ADMIN_ROLE_NAMES, that means nobody can impersonate an account holding an admin role.

Adding Roles

import { defineAdminRBACConfig } from './admin/factory';
export default defineAdminRBACConfig({
roles: { support: 50 },
permissions: {
support: {
user: ['list', 'get', 'ban'],
session: ['list', 'revoke'],
dashboard: ['view'],
},
},
});
  • admin gets every statement, including resources you add, unless you give it permissions.admin.
  • A role with permissions[role] gets exactly that list. Nothing is merged in from defaults.
  • A role without permissions gets nothing.
  • Levels are not a targeting hierarchy here. Unlike organization roles, the kit doesn't check whether one admin role may act on another. Better Auth's only admin-target check is impersonation (it needs impersonate-admins).

New Resources and Explicit Roles

export default defineAdminRBACConfig({
resources: { SUBSCRIPTIONS: 'subscriptions' },
actions: { REFUND: 'refund' },
accessController: { subscriptions: ['list', 'refund'] },
roles: { support: 50 },
permissions: {
support: { subscriptions: ['list'] },
},
});

Here admin gets subscriptions: list, refund automatically, and support gets only subscriptions: list. This also applies to kit updates: if an update adds an admin resource, admin picks it up, but a role you defined with explicit permissions doesn't. That includes admin itself once you set permissions.admin. Review your explicit roles after each kit update.

Invalid config throws AdminRBACConfigError (a subclass of RBACConfigError) when the file loads, with the same messages as organization roles, and accessController follows the same rule: it only adds actions.

Jobs Permissions

/admin/jobs uses four independent statements:

StatementAllows
outbox:listJob list, backlog tiles, dashboard health tile and the organization’s View jobs link
outbox:get/admin/jobs/[id], including attempts, diagnostics and raw metadata
outbox:replayReplay a dead or cancelled job after confirmation and a step-up code
outbox:cancelCancel a pending or retrying job after confirmation and a separate step-up code

The shipped admin role holds all four. A read-only operator can inspect jobs without replaying or cancelling:

export default defineAdminRBACConfig({
roles: { jobReader: 50 },
permissions: {
jobReader: {
dashboard: ['view'],
outbox: ['list', 'get'],
},
},
});

Add organizations: ['view'] if this role should follow organization links. Each loader and POST action checks its own statement; missing permission answers 404. An organization role grants no platform-admin access. Grant replay/cancel only to trusted operators: replay can repeat external side effects, so handlers must be idempotent.

Job metadata must stay ids-only. Detail renders it as stored, with a text-length cap; payloads are never shown. Replay/cancel audit events include job id and kind, never raw metadata or error text. See Jobs in the admin and Retries, dead jobs and replay.

Checking Admin Access

@kit/rbac/admin/client doesn't load better-auth and is safe to import in the browser:

import { adminUserHasPermission, isAdminRole } from '@kit/rbac/admin/client';
isAdminRole(user.role); // true for 'admin' or 'user,admin'
adminUserHasPermission(user.role, 'user', 'ban'); // any listed role grants it

Both split user.role on , without trimming, exactly like Better Auth, so the browser and the server agree: 'user,admin' is an admin, 'user, admin' isn't. Use them to show or hide UI; enforce on the server, inside each action or handler.

It also exports ADMIN_ROLE_NAMES, the ADMIN_* constants, AdminRole/AdminResource/AdminAction, defineAdminRBACConfig and AdminRBACConfigError.

Better Auth Access Control

@kit/rbac/admin re-exports everything above plus the Better Auth objects, and is server-only because it loads better-auth:

import { ADMIN_ROLE_NAMES, adminAc, adminRoles } from '@kit/rbac/admin';
adminRoles.admin.authorize({ user: ['set-role'] }).success; // true

adminAc, adminRoles and ADMIN_ROLE_NAMES are the access controller, roles and admin role names for Better Auth's admin plugin. adminRoles and ADMIN_ROLE_NAMES are frozen.

Common Mistakes

  • Checking member.role. An organization admin isn't a platform admin. Use user.role.
  • Trimming roles yourself. Better Auth doesn't; use isAdminRole so both sides agree.
  • Importing @kit/rbac/admin in a component. It pulls better-auth into the browser bundle. Use @kit/rbac/admin/client.
  • Granting set-role to a junior tier. It can make any account a full admin.

Subject search in filters

User suggestions and selected-name resolution require user:list; organization suggestions require organizations:list. Jobs/Audit read statements alone do not grant directory discovery. The filter lookup returns at most ten id/name/email-or-slug options and uses private, non-cacheable responses.