Collection Access Control

You can define Collection-level Access Control within each Collection's access property. All Access Control functions accept one args argument.

Available Controls

FunctionAllows/Denies Access
createUsed in the create operation
readUsed in the find and findByID operations
updateUsed in the update operation
deleteUsed in the delete operation

Auth-enabled Controls

If a Collection supports Authentication, the following Access Controls become available:

FunctionAllows/Denies Access
adminUsed to restrict access to the Payload Admin panel
unlockUsed to restrict which users can access the unlock operation

Example Collection config:

export default {
slug: "posts",
access: {
create: ({ req: { user } }) => { ... },
read: ({ req: { user } }) => { ... },
update: ({ req: { user } }) => { ... },
delete: ({ req: { user } }) => { ... },
admin: ({ req: { user } }) => { ... },
},
};

Create

Returns a boolean which allows/denies access to the create request.

Available argument properties:

OptionDescription
reqThe Express request object containing the currently authenticated user
dataThe data passed to create the document with.

Example:

const PublicUsers = {
slug: 'public-users',
access: {
// allow guest users to self-registration
create: () => true,
...
},
fields: [ ... ],
}

Read

Read access functions can return a boolean result or optionally return a query constraint which limits the documents that are returned to only those that match the constraint you provide. This can be helpful to restrict users' access to only certain documents however you specify.

Available argument properties:

OptionDescription
reqThe Express request object containing the currently authenticated user
idid of document requested, if within findByID

Example:

const canReadPage = ({ req: { user } }) => {
// allow authenticated users
if (user) {
return true;
}
// using a query constraint, guest users can access when a field named 'isPublic' is set to true
return {
where: {
// assumes we have a checkbox field named 'isPublic'
isPublic: {
equals: true
}
}
}
};

Update

Update access functions can return a boolean result or optionally return a query constraint to limit the document(s) that can be updated by the currently authenticated user. For example, returning a query from the update Access Control is helpful in cases where you would like to restrict a user to only being able to update the documents containing a createdBy relationship field equal to the user's ID.

Available argument properties:

OptionDescription
reqThe Express request object containing the currently authenticated user
idid of document requested to update
dataThe data passed to update the document with

Example:

const canUpdateUser = ({ 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;
};

Delete

Similarly to the Update function, returns a boolean or a query constraint to limit which documents can be deleted by which users.

Available argument properties:

OptionDescription
reqThe Express request object with additional user property, which is the currently logged in user
idid of document requested to delete

Example:

const canDeleteCustomer = 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.payload.find({
collection: 'contracts',
limit: 0,
depth: 0,
where: {
customer: { equals: id },
},
});
return result.totalDocs === 0;
};

Admin

If the Collection is used to access the Payload Admin panel, the Admin Access Control function determines whether or not the currently logged in user can access the admin UI.

Available argument properties:

OptionDescription
reqThe Express request object containing the currently authenticated user

Unlock

Determines which users can unlock other users who may be blocked from authenticating successfully due to failing too many login attempts.

Available argument properties:

OptionDescription
reqThe Express request object containing the currently authenticated user
Next

Field-level Access Control