Simplify your stack and build anything. Or everything.
Build tomorrow’s web with a modern solution you truly own.
Code-based nature means you can build on top of it to power anything.
It’s time to take back your content infrastructure.

Custom Strategies

Creating a strategy

At the core, a strategy is a way to authenticate a user making a request. As of 3.0 we moved away from Passport in favor of pulling back the curtain and putting you in full control.

A strategy is made up of the following:

Parameter

Description

name *

The name of your strategy

authenticate *

A function that takes in the parameters below and returns a user or null.

The authenticate function is passed the following arguments:

Argument

Description

canSetHeaders *

Whether or not the strategy is being executed from a context where response headers can be set. Default is false.

headers *

The headers on the incoming request. Useful for retrieving identifiable information on a request.

payload *

The Payload class. Useful for authenticating the identifiable information against Payload.

isGraphQL

Whether or not the strategy is being executed within the GraphQL endpoint. Default is false.

Example Strategy

At its core a strategy simply takes information from the incoming request and returns a user. This is exactly how Payload's built-in strategies function.

Your authenticate method should return an object containing a Payload user document and any optional headers that you'd like Payload to set for you when we return a response.

1
import type { CollectionConfig } from 'payload'
2
3
export const Users: CollectionConfig = {
4
slug: 'users',
5
auth: {
6
disableLocalStrategy: true,
7
strategies: [
8
{
9
name: 'custom-strategy',
10
authenticate: ({ payload, headers }) => {
11
const usersQuery = await payload.find({
12
collection: 'users',
13
where: {
14
code: {
15
equals: headers.get('code'),
16
},
17
secret: {
18
equals: headers.get('secret'),
19
},
20
},
21
})
22
23
return {
24
// Send the user with the collection slug back to authenticate,
25
// or send null if no user should be authenticated
26
user: usersQuery.docs[0] ? {
27
collection: 'users'
28
...usersQuery.docs[0],
29
} : null,
30
31
// Optionally, you can return headers
32
// that you'd like Payload to set here when
33
// it returns the response
34
responseHeaders: new Headers({
35
'some-header': 'my header value'
36
})
37
}
38
}
39
}
40
]
41
},
42
fields: [
43
{
44
name: 'code',
45
type: 'text',
46
index: true,
47
unique: true,
48
},
49
{
50
name: 'secret',
51
type: 'text',
52
},
53
]
54
}
Next

Token Data