Authentication Overview
Authentication is a critical part of any application. Payload provides a secure, portable way to manage user accounts out of the box. Payload Authentication is designed to be used in both the Admin Panel, as well as your own external applications, completely eliminating the need for paid, third-party platforms and services.
Here are some common use cases of Authentication in your own applications:
- Customer accounts for an e-commerce app
- User accounts for a SaaS product
- P2P apps or social sites where users need to log in and manage their profiles
- Online games where players need to track their progress over time
When Authentication is enabled on a Collection, Payload injects all necessary functionality to support the entire user flow. This includes all auth-related operations like account creation, logging in and out, and resetting passwords, all auth-related emails like email verification and password reset, as well as any necessary UI to manage users from the Admin Panel.
To enable Authentication on a Collection, use the auth property in the Collection Config:

Admin Panel screenshot depicting an Admins Collection with Auth enabled
Config Options
Any Collection can opt-in to supporting Authentication. Once enabled, each Document that is created within the Collection can be thought of as a "user". This enables a complete authentication workflow on your Collection, such as logging in and out, resetting their password, and more.
To enable Authentication on a Collection, use the auth property in the Collection Config:
The hash field stores a PBKDF2-SHA256 derived key prefixed with the scheme it was created with, for example pbkdf2-sha256-v1:<derived-key>. Values stored before that prefix was introduced stay valid and are rewritten to the current scheme after the next successful login, which also assigns a new salt. Treat the stored format as internal and read these fields through Payload rather than deriving them yourself.
New hashes use 600,000 iterations by default. Some environments, such as Cloudflare Workers, do not support more than 100,000 iterations. To support them, set auth.passwordHashIterations in your Payload Config:
Each iteration count uses its own scheme prefix, so hashes created with either count can be verified. After a successful login, a hash with a different count is rehashed with the configured count.
The following options are available:
Option | Description |
|---|---|
| Set cookie options, including |
| How many levels deep a |
| Set to |
| Customize the way that the |
| Set the time (in milliseconds) that a user should be locked out if they fail authentication more times than |
| Ability to allow users to login with username/password. More |
| 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 |
| Set to |
| Set to true if you want to remove the token from the returned authentication API responses such as login or refresh. |
| Advanced - an array of custom authentication strategies to extend this collection's authentication with. More details. |
| How long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time. |
| Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. More details. |
| True by default. Set to |
| Set to |
Disable Local Strategy
The built-in local strategy authenticates users with an email or username and password. It is enabled by default. Set disableLocalStrategy to true to disable it, or to false to explicitly keep it enabled. Only disable the local strategy if you have configured another authentication method, such as API keys or a custom strategy.
You can also pass an object to disable the local strategy while retaining its auth fields:
enableFieldsretains the local auth fields in the database and generated types.optionalPasswordmakes the password field optional when auth fields are retained.
Login With Username
You can allow users to login with their username instead of their email address by setting the loginWithUsername property to true.
Example:
Or, you can pass an object with additional options:
allowEmailLogin
If set to true, users can log in with either their username or email address. If set to false, users can only log in with their username.
requireEmail
If set to true, an email address is required when creating a new user. If set to false, email is not required upon creation.
Auto-Login
For testing and demo purposes you may want to skip forcing the user to login in order to access your application. Typically, all users should be required to login, however, you can speed up local development time by enabling auto-login.
To enable auto-login, set the autoLogin property in the Payload Config:
The following options are available:
Option | Description |
|---|---|
| The username of the user to login as |
| The email address of the user to login as |
| The password of the user to login as. This is only needed if |
| If set to true, the login credentials will be prefilled but the user will still need to click the login button. |
Auto-Refresh
Turning this property on will allow users to stay logged in indefinitely while their browser is open and on the admin panel, by automatically refreshing their authentication token before it expires.
To enable auto-refresh for user tokens, set autoRefresh: true in the Payload Config to:
Refresh Tokens
Apps that aren't always running, like mobile apps or CLIs, can't refresh their token before it expires. With refreshTokens, login also returns a refresh token, which the refresh operation trades for a new token and a new refresh token, even after the token expired:
Refresh tokens don't expire on their own. They work as long as their session, which lasts expiration from the last refresh instead of tokenExpiration. The token itself still expires after tokenExpiration.
Each refresh token is meant to be used once, so store the new one after every refresh. For 30 seconds after a refresh, the refresh token from right before it still works, so clients that refresh twice at once stay logged in. If a used refresh token comes back otherwise, Payload treats it as copied and logs out its session. Logging out ends refresh tokens too. They require useSessions, and aren't returned with removeTokenFromResponses.
Sessions
By default, Payload saves each login as a session on the user, and logging out ends it. Besides when it was created and when it expires, each session can say what it is:
label: for people to read, e.g. "Chrome on macOS".type: how the session was created. Logins use'login'. Plugins can use their own values, e.g.'mcp'.metadata: anything else to show next to the label, as JSON.
A login sets type to 'login', and label to the browser and operating system from its User-Agent. Code that starts a session itself with createAuthToken can pass its own:
Operations
All auth-related operations are available via Payload's REST, Local, and GraphQL APIs. These operations are automatically added to your Collection when you enable Authentication. More details.
Strategies
Out of the box Payload ships with three powerful Authentication strategies:
Each of these strategies can work together or independently. You can also create your own custom strategies to fit your specific needs. More details.
HTTP-Only Cookies
HTTP-only cookies are a highly secure method of storing identifiable data on a user's device so that Payload can automatically recognize a returning user until their cookie expires. They are totally protected from common XSS attacks and cannot be read by JavaScript in the browser, unlike JWT's. More details.
JSON Web Tokens
JWT (JSON Web Tokens) can also be utilized to perform authentication. Tokens are generated on login, refresh and me operations and can be attached to future requests to authenticate users. More details.
API Keys
API Keys can be enabled on auth collections. These are particularly useful when you want to authenticate against Payload from a third party service. More details.
Custom Strategies
There are cases where these may not be enough for your application. Payload is extendable by design so you can wire up your own strategy when you need to. More details.
Access Control
Default auth fields including email, username, and password can be overridden by defining a custom field with the same name in your collection config. This allows you to customize the field — including access control — while preserving the underlying auth functionality. For example, you might want to restrict the email field from being updated once it is created, or only allow it to be read by certain user roles. You can achieve this by redefining the field and setting access rules accordingly.
Here's an example of how to restrict access to default auth fields:
Note:
- Access functions will apply across the application — I.e. if
readaccess is disabled onemail, it will not appear in the Admin panel UI or API. - Restricting
readon theemailorusernamedisables the Unlock action in the Admin panel as this function requires access to a user-identifying field. - When overriding the
passwordfield, you may need to includehidden: trueto prevent duplicate fields being displayed in the Admin panel.
Was this page helpful?