# RBAC Permissions

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/admin/rbac-permissions*

---

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](../members-management/roles-permissions), 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 roles | Admin roles |
|---|---|---|
| Stored on | `member.role` (per organization) | `user.role` (per account) |
| Configured in | `rbac.config.ts` | `admin-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:

| Resource | Actions |
|---|---|
| `user` | `create`, `list`, `get`, `update`, `set-role`, `set-password`, `set-email`, `ban`, `impersonate`, `delete` |
| `session` | `list`, `revoke`, `delete` |
| `organizations` | `list`, `view` |
| `dashboard` | `view` |
| `audit` | `list` |
| `outbox` | `list`, `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

```ts
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`).

{% callout type="warning" title="Three rules that protect every account" %}
- `user: ['set-role']` can assign any role, `admin` included. A tier that holds it can promote an account to full admin, so grant it only to roles you'd trust as full admins.
- The kit's own ban and sign-out actions refuse any account with an admin role, and nobody can change their own role. Better Auth's endpoints don't check targets (`set-password`, `set-email`, `update`, `delete`): the kit closes them over HTTP, so if you add an action that calls them, add your own target check.
- An admin role named `user` throws `AdminRBACConfigError` with code `RESERVED_ROLE`. Every account has `user.role = 'user'`, so that name would make every signup an admin.
{% /callout %}

### New Resources and Explicit Roles

```ts
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](../members-management/roles-permissions#validation), and `accessController` follows the same rule: it only adds actions.

## Jobs Permissions

`/admin/jobs` uses four independent statements:

| Statement | Allows |
|---|---|
| `outbox:list` | Job 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:replay` | Replay a dead or cancelled job after confirmation and a step-up code |
| `outbox:cancel` | Cancel 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:

```ts
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](./overview#jobs) and [Retries, dead jobs and replay](../outbox/failures).

## Checking Admin Access

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

```ts
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`:

```ts
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.

## Related

- [Roles and Permissions](../members-management/roles-permissions): organization roles and the shared merge and validation rules.
- [Authorization Policies](../development-guide/authorization-policies): business rules beyond permissions.

### 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.
