Collection Access Control

Collection Access Control is Access Control used to restrict access to Documents within a Collection, as well as what they can and cannot see within the Admin Panel as it relates to that Collection.

To add Access Control to a Collection, use the access property in your Collection Config:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithAccessControl: CollectionConfig = {
4  // ...
5  access: {
6    
7    // ...
8  },
9}

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:

1import type { CollectionConfig } from 'payload';
2
3export const CollectionWithAccessControl: CollectionConfig = {
4  // ...
5  access: {
6    create: () => {...},
7    read: () => {...},
8    update: () => {...},
9    delete: () => {...},
10    validate: () => {...},
11
12    // Auth-enabled Collections only
13    admin: () => {...},
14    unlock: () => {...},
15
16    // Version-enabled Collections only
17    readVersions: () => {...},
18  },
19}

The following options are available:

Function	Allows/Denies Access
`create`	Used in the `create` operation. More details.
`read`	Used in the `find` and `findByID` operations. More details.
`update`	Used in the `update` operation. More details.
`delete`	Used in the `delete` operation. More details.
`validate`	Optionally overrides `update` access for on-demand validation.

If a Collection supports Authentication, the following additional options are available:

Function	Allows/Denies Access
`admin`	Used to restrict access to the Admin Panel. More details.
`unlock`	Used to restrict which users can access the `unlock` operation. More details.

If a Collection supports Versions, the following additional options are available:

Function	Allows/Denies Access
`readVersions`	Used to control who can read versions, and who can't. Will automatically restrict the Admin UI version viewing access. More details.

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:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithCreateAccess: CollectionConfig = {
4  // ...
5  access: {
6    create: ({ req: { user }, data }) => {
7      return Boolean(user)
8    },
9  },
10}

The following arguments are provided to the create function:

Option	Description
`req`	The Request object containing the currently authenticated `user`.
`data`	The data passed to create the document with.
`slug`	The slug of the Collection being accessed.

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:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithReadAccess: CollectionConfig = {
4  // ...
5  access: {
6    read: ({ req: { user } }) => {
7      return Boolean(user)
8    },
9  },
10}

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

1import type { Access } from 'payload'
2import type { Page } from '@/payload-types'
3
4export const canReadPage: Access<Page> = ({ req: { user } }) => {
5  // Allow authenticated users
6  if (user) {
7    return true
8  }
9
10  // By returning a Query, guest users can read public Documents
11  // Note: this assumes you have a `isPublic` checkbox field on your Collection
12  return {
13    isPublic: {
14      equals: true,
15    },
16  }
17}

The following arguments are provided to the read function:

Option	Description
`req`	The Request object containing the currently authenticated `user`.
`id`	`id` of document requested, if within `findByID`.
`slug`	The slug of the Collection being accessed.

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:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithUpdateAccess: CollectionConfig = {
4  // ...
5  access: {
6    update: ({ req: { user } }) => {
7      return Boolean(user)
8    },
9  },
10}

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

1import type { Access } from 'payload'
2import type { User } from '@/payload-types'
3
4export const canUpdateUser: Access<User> = ({ req: { user }, id }) => {
5  // Allow users with a role of 'admin'
6  if (user.roles && user.roles.some((role) => role === 'admin')) {
7    return true
8  }
9
10  // allow any other users to update only oneself
11  return user.id === id
12}

The following arguments are provided to the update function:

Option	Description
`req`	The Request object containing the currently authenticated `user`.
`id`	`id` of document requested to update.
`data`	The data passed to update the document with.
`slug`	The slug of the Collection being accessed.

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:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithDeleteAccess: CollectionConfig = {
4  // ...
5  access: {
6    delete: ({ req: { user } }) => {
7      return Boolean(user)
8    },
9  },
10}

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

1import type { Access } from 'payload'
2import type { Customer } from '@/payload-types'
3
4export const canDeleteCustomer: Access<Customer> = async ({ req, id }) => {
5  if (!id) {
6    // allow the admin UI to show controls to delete since it is indeterminate without the `id`
7    return true
8  }
9
10  // Query another Collection using the `id`
11  const result = await req.payload.find({
12    collection: 'contracts',
13    overrideAccess: true,
14    limit: 0,
15    depth: 0,
16    where: {
17      customer: { equals: id },
18    },
19  })
20
21  return result.totalDocs === 0
22}

The following arguments are provided to the delete function:

Option	Description
`req`	The Request object with additional `user` property, which is the currently logged in user.
`id`	`id` of document requested to delete.
`data`	The data being set on the document. For Trash-enabled collections, check `data.deletedAt` to differentiate between soft delete and permanent delete operations.
`slug`	The slug of the Collection being accessed.

Admin

If the Collection is used to access the Admin Panel, the Admin Access Control function determines whether or not 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:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithAdminAccess: CollectionConfig = {
4  // ...
5  access: {
6    admin: ({ req: { user } }) => {
7      return Boolean(user)
8    },
9  },
10}

The following arguments are provided to the admin function:

Option	Description
`req`	The Request object containing the currently authenticated `user`.
`slug`	The slug of the Collection being accessed.

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:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithUnlockAccess: CollectionConfig = {
4  // ...
5  access: {
6    unlock: ({ req: { user } }) => {
7      return Boolean(user)
8    },
9  },
10}

The following arguments are provided to the unlock function:

Option	Description
`req`	The Request object containing the currently authenticated `user`.
`slug`	The slug of the Collection being accessed.

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.

If readVersions is not configured, Payload uses the Collection's read Access Control. Boolean results are preserved, and query constraints are automatically adjusted to target fields within the stored version document.

For findVersionByID, the inherited read function receives the parent Document's id, not the version record's id.

To add Read Versions Access Control to a Collection, use the readVersions property in the Collection Config:

1import type { CollectionConfig } from 'payload'
2
3export const CollectionWithVersionsAccess: CollectionConfig = {
4  // ...
5  access: {
6    readVersions: ({ req: { user } }) => {
7      return Boolean(user)
8    },
9  },
10}

The following arguments are provided to the readVersions function:

Option	Description
`req`	The Request object containing the currently authenticated `user`.
`slug`	The slug of the Collection being accessed.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Collection Access Control

Config Options

Create

Read

Update

Delete

Admin

Unlock

Read Versions

Globals Access Control