Roles

The roles plugin stores code-defined role assignments on users and provides access helpers. It does not add access rules to your collections.

Install

pnpm add @frogbotai/plugin-roles

Define roles

import { rolesPlugin } from '@frogbotai/plugin-roles'
import { buildConfig } from 'frogbot'

export default buildConfig({
  collections: [
    {
      slug: 'users',
      auth: true,
      fields: [],
    },
  ],
  plugins: [
    rolesPlugin({
      roles: [
        'admin',
        'member',
        'finance',
        { slug: 'compliance', label: 'Compliance Officer' },
      ],
    }),
  ],
})

When roles are listed, the plugin adds a roles multi-select field to the users auth collection. Assignments are stored as slugs. There is no role-definition collection. Roles are literal strings. No slug is reserved, and no role receives implicit access. admin is a common convention, but it is not a superuser unless your access functions grant it. rolesPlugin() and rolesPlugin({ roles: [] }) are inert and add no field. The plugin runs with order: 100, after other first-party plugins, so it binds allow() clauses on the collections they add wherever you list it.

Apply access

allow(...clauses) composes role, ownership, and function clauses into a FrogBot access function:

import { allow, hasRole, ownRows } from '@frogbotai/plugin-roles'

const projects = {
  slug: 'projects',
  access: {
    create: allow({ role: 'member', own: 'owner' }),
    read: allow('admin', 'finance', { role: 'member', own: 'owner' }),
    update: allow('admin', { role: 'member', own: 'owner' }),
    delete: allow('admin'),
  },
  fields: [
    {
      name: 'owner',
      type: 'relationship',
      relationTo: 'users',
      required: true,
    },
    {
      name: 'reviewNotes',
      type: 'text',
      access: {
        read: allow('admin', 'compliance'),
        update: allow('compliance'),
      },
    },
  ],
}

const invoices = {
  slug: 'invoices',
  access: {
    read: ({ req }) => hasRole(req, 'admin', 'finance') || ownRows(req, 'user'),
  },
  fields: [],
}

Every role must be written where it should apply. For example, allow('finance') denies a user assigned only admin; use allow('admin', 'finance') to grant both. An ownership clause names a relationship field. On create, FrogBot stamps that field when the matching role grants access. On read, update, and delete, it returns an ownership query. Function clauses returning false abstain rather than vetoing another clause. Ownership and Where clauses are for collection access. Boolean role and function clauses also work in field and agent access.

Request helpers

import { hasRole, isLoggedIn, ownRows, rolesOf, viaApiKey } from '@frogbotai/plugin-roles'

isLoggedIn(req)
hasRole(req, 'finance', 'auditor')
rolesOf(req)
ownRows(req, 'owner')
viaApiKey(req)

Helper	Result
`isLoggedIn(req)`	Whether `req.user` exists.
`hasRole(req, ...roles)`	Whether the user has any supplied literal role.
`rolesOf(req)`	Effective role slugs for the request.
`ownRows(req, field)`	An ownership query, or `false` without a user.
`viaApiKey(req)`	Whether authentication used the API-key strategy.

Role field access

The injected roles field uses FrogBot’s default field access. Use rolesFieldAccess when role assignments need different access rules:

rolesPlugin({
  roles: ['owner', 'member'],
  rolesFieldAccess: {
    read: ({ req }) => req.user?.id === req.data?.id,
    update: ({ req }) => hasRole(req, 'owner'),
  },
})

The object is passed directly to the injected field.

Default role

By default, new users receive no role. Set defaultRole to configure the injected field’s defaultValue:

rolesPlugin({
  roles: ['admin', 'member'],
  defaultRole: 'member',
})

The default must be listed in roles. Explicit assignments, including roles: [], are preserved. Existing users are unchanged.

Custom role sources

By default, helpers read req.user.roles. Use resolveRoles when assignments come from another synchronous source, such as JWT claims or tenant membership:

rolesPlugin({
  roles: ['admin', 'member'],
  resolveRoles: (req) => req.user?.tenantRoles ?? [],
})

The resolver must return listed slugs. Its result is cached once per request and shared by predicates and allow() clauses.

Bootstrap access

The plugin does not promote the first user. Bootstrap privileged assignments explicitly with FrogBot’s Local API from a seed or migration, with overrideAccess: true:

await frogbot.update({
  collection: 'users',
  overrideAccess: true,
  id: ownerUserId,
  data: { roles: ['admin'] },
})

You can also assign roles when seeding users:

await frogbot.create({
  collection: 'users',
  overrideAccess: true,
  data: { email, password, roles: ['admin'] },
})

For application-managed onboarding, add a userland collection hook that derives the assignment from your own invite, tenant, or deployment rules. Keep that bootstrap condition in application code and remove or disable one-time logic after it succeeds.

Options

Option	Type	Default	Description
`roles`	`(string \| { slug: string; label?: string })[]`	`[]`	Role slugs, optionally with an admin label. Labels default to the slug in title case. Duplicate slugs throw at startup. With no roles, the plugin is inert.
`defaultRole`	`string`	—	Role assigned to new users through the injected field’s `defaultValue`. Must be listed in `roles`.
`resolveRoles`	`(req: FrogBotRequest) => RoleSlug[]`	Reads `req.user.roles`	Synchronous resolver for a request’s roles. See Custom role sources.
`rolesFieldAccess`	`{ create?: FieldAccess; read?: FieldAccess; update?: FieldAccess }`	Default field access	Access for the injected `roles` field. See Role field access.

The plugin injects the roles field into the users collection only, and only when that collection has auth enabled; with roles configured and no auth-enabled users collection, it logs a warning at startup. It throws at startup if users already has a field named roles, or if an allow() clause names a role that isn’t listed. RoleSlug is imported from @frogbotai/plugin-roles. frogbot generate:types types it as the union of the configured role slugs, so resolveRoles and hasRole() reject unknown roles. Without generated types it’s string.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Install

Define roles

Apply access

Request helpers

Role field access

Default role

Custom role sources

Bootstrap access

Options

​Install

​Define roles

​Apply access

​Request helpers

​Role field access

​Default role

​Custom role sources

​Bootstrap access

​Options

Install

Define roles

Apply access

Request helpers

Role field access

Default role

Custom role sources

Bootstrap access

Options