Payload's Authentication is extremely powerful and gives you everything you need when you go to build a new app or site in a secure and responsible manner.
To enable Authentication on a collection, define an auth
property and set it to either true
or to an object containing the options below.
Option | Description |
---|---|
useAPIKey | Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. More |
tokenExpiration | How long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time. |
maxLoginAttempts | Only allow a user to attempt logging in X amount of times. Automatically locks out a user from authenticating if this limit is passed. Set to 0 to disable. |
lockTime | Set the time that a user should be locked out if they fail authentication more times than maxLoginAttempts allows for. |
depth | How many levels deep a user document should be populated when creating the JWT and binding the user to the express req . Defaults to 0 and should only be modified if absolutely necessary, as this will affect performance. |
cookies | Set cookie options, including secure , sameSite , and domain . For advanced users. |
forgotPassword | Customize the way that the forgotPassword operation functions. More |
verify | Set to true or pass an object with verification options to require users to verify by email before they are allowed to log into your app. More |
To integrate with third-party APIs or services, you might need the ability to generate API keys that can be used to identify as a certain user within Payload.
For example, if you have a third-party service or external app that needs to be able to perform protected actions at its discretion, you have two options:
Technically, both of these options will work for third-party integrations but the second option with API key is simpler, because it reduces the amount of work that your integrations need to do to be authenticated properly.
To enable API keys on a collection, set the useAPIKey
auth option to true
. From there, a new interface will appear in the Admin panel for each document within the collection that allows you to generate an API key for each user in the Collection.
To utilize your API key while interacting with the REST or GraphQL API, add the Authorization
header.
For example, using Fetch:
const response = await fetch('http://localhost:3000/api/pages', {headers: {Authorization: `${collection.labels.singular} API-Key ${YOUR_API_KEY}`,},});
You can customize how the Forgot Password workflow operates with the following options on the auth.forgotPassword
property:
generateEmailHTML
Function that accepts one argument, containing { req, token, user }
, that allows for overriding the HTML within emails that are sent to users attempting to reset their password. The function should return a string that supports HTML, which can be a full HTML email.
Example:
{slug: 'customers',auth: {forgotPassword: {generateEmailHTML: ({ req, token, user }) => {// Use the token provided to allow your user to reset their passwordconst resetPasswordURL = `https://yourfrontend.com/reset-password?token=${token}`;return `<!doctype html><html><body><h1>Here is my custom email template!</h1><p>Hello, ${user.email}!</p><p>Click below to reset your password.</p><p><a href="${resetPasswordURL}">${resetPasswordURL}</a></p></body></html>`;}}}}
generateEmailSubject
Similarly to the above generateEmailHTML
, you can also customize the subject of the email. The function argument are the same but you can only return a string - not HTML.
Example:
{slug: 'customers',auth: {forgotPassword: {generateEmailSubject: ({ req, user }) => {return `Hey ${user.email}, reset your password!`;}}}}
If you'd like to require email verification before a user can successfully log in, you can enable it by passing true
or an options
object to auth.verify
. The following options are available:
generateEmailHTML
Function that accepts one argument, containing { req, token, user }
, that allows for overriding the HTML within emails that are sent to users indicating how to validate their account. The function should return a string that supports HTML, which can optionally be a full HTML email.
Example:
{slug: 'customers',auth: {verify: {generateEmailHTML: ({ req, token, user }) => {// Use the token provided to allow your user to verify their accountconst url = `https://yourfrontend.com/verify?token=${token}`;return `Hey ${user.email}, verify your email by clicking here: ${url}`;}}}}
generateEmailSubject
Similarly to the above generateEmailHTML
, you can also customize the subject of the email. The function argument are the same but you can only return a string - not HTML.
Example:
{slug: 'customers',auth: {forgotPassword: {generateEmailSubject: ({ req, user }) => {return `Hey ${user.email}, reset your password!`;}}}}