Collection Access Control

Collection Access Control is Access Control used to restrict access to Documents within a Collection, as well as what users can see in the Admin Panel for that Collection. To add Access Control to a Collection, use the access property in your Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithAccessControl: CollectionConfig = {
  // ...
  access: {
    // ...
  },
}

Config Options

Access Control is specific to the operation of the request. To add Access Control to a Collection, use the access property in your Collection Config:

import type { CollectionConfig } from 'frogbot';

export const CollectionWithAccessControl: CollectionConfig = {
  // ...
  access: {
    create: () => {...},
    read: () => {...},
    update: () => {...},
    delete: () => {...},

    // Auth-enabled Collections only
    admin: () => {...},
    unlock: () => {...},

    // Version-enabled Collections only
    readVersions: () => {...},
  },
}

The following options are available:

Function	Type	Default	Allows/Denies Access
`create`	`Access`	Signed-in users	Used in the `create` operation. More details.
`read`	`Access`	Signed-in users	Used in the `find`, `findByID`, `count`, and `findDistinct` operations, and for file downloads. More details.
`update`	`Access`	Signed-in users	Used in the `update` operation. More details.
`delete`	`Access`	Signed-in users	Used in the `delete` operation, and when trashing a document. More details.
`admin`	`({ req }) => boolean \| Promise<boolean>`	Users of the `admin.user` collection	Auth collections only. Restricts access to the Admin Panel. More details.
`unlock`	`Access`	Signed-in users of the `admin.user` collection	Auth collections only. Restricts which users can run the `unlock` operation. More details.
`readVersions`	`Access`	Signed-in users	Version-enabled collections only. Controls who can read versions. Will automatically restrict the Admin UI version viewing access. More details.

Every function except admin returns true, false, or a query that limits which documents the operation applies to.

Create

Returns a boolean which allows/denies access to the create request. To add create Access Control to a Collection, use the create property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithCreateAccess: CollectionConfig = {
  // ...
  access: {
    create: ({ req: { user }, data }) => {
      return Boolean(user)
    },
  },
}

The following arguments are provided to the create function:

Option	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The current request, with the signed-in `user` and `req.frogbot`.
`data`	`object`	Set on `create`	The data passed to create the document with.
`id`	`string \| number`	—	Not set for `create`.
`slug`	`string`	Always set	The slug of this collection.
`isReadingStaticFile`	`boolean`	`false`	`true` when the check runs for a request to download an upload collection’s file.

Read

Returns a boolean which allows/denies access to the read request. To add read Access Control to a Collection, use the read property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithReadAccess: CollectionConfig = {
  // ...
  access: {
    read: ({ req: { user } }) => {
      return Boolean(user)
    },
  },
}

Return a Query to limit the Documents to only those that match the constraint. This can be helpful to restrict users’ access to specific Documents. More details.

As your application becomes more complex, you may want to define your function in a separate file and import them into your Collection Config:

import type { Access } from 'frogbot'
import type { Page } from '@/frogbot-types'

export const canReadPage: Access<Page> = ({ req: { user } }) => {
  // Allow authenticated users
  if (user) {
    return true
  }

  // By returning a Query, guest users can read public Documents
  // Note: this assumes you have a `isPublic` checkbox field on your Collection
  return {
    isPublic: {
      equals: true,
    },
  }
}

The following arguments are provided to the read function:

Option	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The current request, with the signed-in `user` and `req.frogbot`.
`id`	`string \| number`	Set in `findByID`	`id` of the requested document. Not set in `find`, so return a query to limit which documents are returned.
`data`	`object`	Set for file downloads	`{ filename }` when an upload collection’s file is requested.
`slug`	`string`	Always set	The slug of this collection.
`isReadingStaticFile`	`boolean`	`false`	`true` when the check runs for a request to download an upload collection’s file.

Update

Returns a boolean which allows/denies access to the update request. To add update Access Control to a Collection, use the update property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithUpdateAccess: CollectionConfig = {
  // ...
  access: {
    update: ({ req: { user } }) => {
      return Boolean(user)
    },
  },
}

Return a Query to limit the Documents to only those that match the constraint. This can be helpful to restrict users’ access to specific Documents. More details.

As your application becomes more complex, you may want to define your function in a separate file and import them into your Collection Config:

import type { Access } from 'frogbot'
import type { User } from '@/frogbot-types'

export const canUpdateUser: Access<User> = ({ req: { user }, id }) => {
  // Allow users with a role of 'admin'
  if (user.roles && user.roles.some((role) => role === 'admin')) {
    return true
  }

  // allow any other users to update only oneself
  return user.id === id
}

The following arguments are provided to the update function:

Option	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The current request, with the signed-in `user` and `req.frogbot`.
`id`	`string \| number`	Set for update by ID	`id` of the document to update. Not set for bulk updates.
`data`	`object`	Always set	The data passed to update the document with.
`slug`	`string`	Always set	The slug of this collection.
`isReadingStaticFile`	`boolean`	`false`	`true` when the check runs for a request to download an upload collection’s file.

For Collections with Drafts enabled, you can use update access to control who can publish by returning a query constraint on the _status field.

Delete

Similarly to the Update function, returns a boolean or a query constraint to limit which documents can be deleted by which users. To add delete Access Control to a Collection, use the delete property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithDeleteAccess: CollectionConfig = {
  // ...
  access: {
    delete: ({ req: { user } }) => {
      return Boolean(user)
    },
  },
}

As your application becomes more complex, you may want to define your function in a separate file and import them into your Collection Config:

import type { Access } from 'frogbot'
import type { Customer } from '@/frogbot-types'

export const canDeleteCustomer: Access<Customer> = async ({ req, id }) => {
  if (!id) {
    // allow the admin UI to show controls to delete since it is indeterminate without the `id`
    return true
  }

  // Query another Collection using the `id`
  const result = await req.frogbot.find({
    collection: 'contracts',
    overrideAccess: true,
    limit: 0,
    depth: 0,
    where: {
      customer: { equals: id },
    },
  })

  return result.totalDocs === 0
}

The following arguments are provided to the delete function:

Option	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The current request, with the signed-in `user` and `req.frogbot`.
`id`	`string \| number`	Set for delete by ID	`id` of the document to delete. Not set for bulk deletes, or when the admin panel checks permissions without a document.
`data`	`object`	Set when trashing	The data being set on the document. For Trash-enabled collections, `delete` access also runs during updates; check `data.deletedAt` to differentiate between soft delete and permanent delete operations.
`slug`	`string`	Always set	The slug of this collection.
`isReadingStaticFile`	`boolean`	`false`	`true` when the check runs for a request to download an upload collection’s file.

For Collections with Trash enabled, you can use the data argument to allow users to soft delete (trash) documents while restricting permanent deletion. See Trash Access Control for examples.

Admin

If the Collection is used to access the Admin Panel, the Admin Access Control function determines whether the currently logged-in user can access the admin UI. To add Admin Access Control to a Collection, use the admin property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithAdminAccess: CollectionConfig = {
  // ...
  access: {
    admin: ({ req: { user } }) => {
      return Boolean(user)
    },
  },
}

The following arguments are provided to the admin function:

Option	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The current request, with the signed-in `user` and `req.frogbot`.
`slug`	`string`	Always set	The slug of this collection.

Unlock

Determines which users can unlock other users who may be blocked from authenticating successfully due to failing too many login attempts. To add Unlock Access Control to a Collection, use the unlock property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithUnlockAccess: CollectionConfig = {
  // ...
  access: {
    unlock: ({ req: { user } }) => {
      return Boolean(user)
    },
  },
}

The following arguments are provided to the unlock function:

Option	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The current request, with the signed-in `user` and `req.frogbot`.
`slug`	`string`	Always set	The slug of this collection.
`id`	`string \| number`	—	Not set for `unlock`.
`data`	`object`	—	Not set for `unlock`.
`isReadingStaticFile`	`boolean`	`false`	`true` when the check runs for a request to download an upload collection’s file.

Read Versions

If the Collection has Versions enabled, the readVersions Access Control function determines whether or not the currently logged in user can access the version history of a Document. To add Read Versions Access Control to a Collection, use the readVersions property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithVersionsAccess: CollectionConfig = {
  // ...
  access: {
    readVersions: ({ req: { user } }) => {
      return Boolean(user)
    },
  },
}

Returning a Query will apply the constraint to the versions collection, not the original Collection.

The following arguments are provided to the readVersions function:

Option	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The current request, with the signed-in `user` and `req.frogbot`.
`id`	`string \| number`	Set in `findVersionByID`	`id` of the requested version.
`data`	`object`	—	Not set for `readVersions`.
`slug`	`string`	Always set	The slug of this collection.
`isReadingStaticFile`	`boolean`	`false`	`true` when the check runs for a request to download an upload collection’s file.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Collection Access Control

Config Options

Create

Read

Update

Delete

Admin

Unlock

Read Versions

​Config Options

​Create

​Read

​Update

​Delete

​Admin

​Unlock

​Read Versions

Config Options

Create

Read

Update

Delete

Admin

Unlock

Read Versions