Skip to content

Commit b809c98

Browse files
authored
docs: adds server function and access control sections to local API docs (#11902)
### What? Adds 2 new topics to our Local API docs: - Using server functions with local API ops - Respecting access control Will also be updating the server function docs with `reusable server functions` once #11900 is merged.
1 parent b9ffbc6 commit b809c98

File tree

2 files changed

+411
-0
lines changed

2 files changed

+411
-0
lines changed

docs/local-api/access-control.mdx

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Respecting Access Control with Local API Operations
3+
label: Access Control
4+
order: 40
5+
desc: Learn how to implement and enforce access control in Payload's Local API operations, ensuring that the right permissions are respected during data manipulation.
6+
keywords: server functions, local API, Payload, CMS, access control, permissions, user context, server-side logic, custom workflows, data management, headless CMS, TypeScript, Node.js, backend
7+
---
8+
9+
## Understanding Access Control in Local API Operations
10+
11+
In Payload, local API operations **override access control by default**. This means that operations will run without checking if the current user has permission to perform the action. This is useful in certain scenarios where access control is not necessary, but it is important to be aware of when to enforce it for security reasons.
12+
13+
### **Default Behavior: Access Control Skipped**
14+
15+
By default, **local API operations skip access control**. This allows operations to execute without the system checking if the current user has appropriate permissions. This might be helpful in admin or server-side scripts where the user context is not required to perform the operation.
16+
17+
#### For example:
18+
19+
```ts
20+
// Access control is this operation would be skipped by default
21+
const test = await payload.create({
22+
collection: 'users',
23+
data: {
24+
email: 'test@test.com',
25+
password: 'test',
26+
},
27+
})
28+
```
29+
30+
### **Respecting Access Control**
31+
32+
If you want to **respect access control** and ensure that the operation is performed only if the user has appropriate permissions, you need to explicitly pass the `user` object and set the `overrideAccess` option to `false`.
33+
34+
- **`overrideAccess: false`**: This ensures that access control is **not skipped** and the operation respects the current user's permissions.
35+
- **`user`**: Pass the authenticated user context to the operation. This ensures the system checks whether the user has the right permissions to perform the action.
36+
37+
```ts
38+
const authedCreate = await payload.create({
39+
collection: 'users',
40+
overrideAccess: false, // This ensures access control will be applied
41+
user, // Pass the authenticated user to check permissions
42+
data: {
43+
email: 'test@test.com',
44+
password: 'test',
45+
},
46+
})
47+
```
48+
49+
This example will only allow the document to be created if the `user` we passed has the appropriate access control permissions.

0 commit comments

Comments
 (0)