--- title: Authentication Config label: Config order: 20 desc: Enable and customize options in the Authentication config for features including Forgot Password, Login Attempts, API key usage and more. keywords: authentication, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- 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. ## Options | Option | Description | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **`useAPIKey`** | Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. [More](/docs/authentication/config#api-keys) | | **`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 (in milliseconds) 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 `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](/docs/authentication/config#forgot-password) | | **`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](/docs/authentication/config#email-verification) | | **`disableLocalStrategy`** | Advanced - disable Payload's built-in local auth strategy. Only use this property if you have replaced Payload's auth mechanisms with your own. | | **`strategies`** | Advanced - an array of custom authentification strategies to extend this collection's authentication with. [More](/docs/authentication/custom-strategies) | ### Forgot Password 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. Tip:
HTML templating can be used to create custom email templates, inline CSS automatically, and more. You can make a reusable function that standardizes all email sent from Payload, which makes sending custom emails more DRY. Payload doesn't ship with an HTML templating engine, so you are free to choose your own. Example: ```ts import { CollectionConfig } from 'payload' export const Customers: CollectionConfig = { slug: 'customers', auth: { forgotPassword: { // highlight-start generateEmailHTML: ({ req, token, user }) => { // Use the token provided to allow your user to reset their password const resetPasswordURL = `https://yourfrontend.com/reset-password?token=${token}` return `

Here is my custom email template!

Hello, ${user.email}!

Click below to reset your password.

${resetPasswordURL}

` }, // highlight-end }, }, } ``` Important:
If you specify a different URL to send your users to for resetting their password, such as a page on the frontend of your app or similar, you need to handle making the call to the Payload REST or GraphQL reset-password operation yourself on your frontend, using the token that was provided for you. Above, it was passed via query parameter. **`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: ```ts { slug: 'customers', auth: { forgotPassword: { // highlight-start generateEmailSubject: ({ req, user }) => { return `Hey ${user.email}, reset your password!`; } // highlight-end } } } ``` ### Email Verification 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: ```ts import { CollectionConfig } from 'payload' export const Customers: CollectionConfig = { slug: 'customers', auth: { verify: { // highlight-start generateEmailHTML: ({ req, token, user }) => { // Use the token provided to allow your user to verify their account const url = `https://yourfrontend.com/verify?token=${token}` return `Hey ${user.email}, verify your email by clicking here: ${url}` }, // highlight-end }, }, } ``` Important:
If you specify a different URL to send your users to for email verification, such as a page on the frontend of your app or similar, you need to handle making the call to the Payload REST or GraphQL verification operation yourself on your frontend, using the token that was provided for you. Above, it was passed via query parameter. **`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: ```ts { slug: 'customers', auth: { forgotPassword: { // highlight-start generateEmailSubject: ({ req, user }) => { return `Hey ${user.email}, reset your password!`; } // highlight-end } } } ``` ### Admin autologin For testing and demo purposes you may want to skip forcing the admin user to login in order to access the panel. The `admin.autologin` property is used to configure the how visitors are handled when accessing the Admin Panel. The default is that all users will have to login and this should not be enabled for environments where data needs to protected. #### autoLogin Options | Option | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------- | | **`email`** | The email address of the user to login as | | **`password`** | The password of the user to login as | | **`prefillOnly`** | If set to true, the login credentials will be prefilled but the user will still need to click the login button. | The recommended way to use this feature is behind an environment variable to ensure it is disabled when in production. **Example:** ```ts export default buildConfig({ admin: { user: 'users', // highlight-start autoLogin: process.env.PAYLOAD_PUBLIC_ENABLE_AUTOLOGIN === 'true' ? { email: 'test@example.com', password: 'test', prefillOnly: true, } : false, // highlight-end }, collections: [ /** */ ], }) ```