payload 1.15.6 → 2.0.0-beta.0

package/docs/authentication/config.mdx

@@ -1,287 +0,0 @@
----
-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, express
----
-
-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 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](/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 PassportJS authentication strategies to extend this collection's authentication with. [More](/docs/authentication/config#strategies)                                                                         |
-
-### API keys
-
-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.
-
-In Payload, users are essentially documents within a collection. Just like you can authenticate as a user with an email and password, which is considered as our default local auth strategy, you can also authenticate as a user with an API key. API keys are generated on a user-by-user basis, similar to email and passwords, and are meant to represent a single user.
-
-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:
-
-1. Create a user for the third-party app, and log in each time to receive a token before you attempt to access any protected actions
-1. Enable API key support for the Collection, where you can generate a non-expiring API key per user in the collection. This is particularly useful as you can create a "user" that reflects an integration with a specific external service and assign a "role" or specific access only needed by that service/integration. Alternatively, you could create a "super admin" user and assign an API key to that user so that any requests made with that API key are considered as being made by that super user.
-
-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.
-
-<Banner type="success">
-  User API keys are encrypted within the database, meaning that if your database
-  is compromised, your API keys will not be.
-</Banner>
-
-#### Authenticating via API Key
-
-To authenticate REST or GraphQL API requests using an API key, set the `Authorization` header. The header is case-sensitive and needs the slug of the `auth.useAPIKey` enabled collection, then " API-Key ", followed by the `apiKey` that has been assigned. Payload's built-in middleware will then assign the user document to `req.user` and handle requests with the proper access control. By doing this, Payload recognizes the request being made as a request by the user associated with that API key.
-
-**For example, using Fetch:**
-
-```ts
-import User from '../collections/User';
-
-const response = await fetch("http://localhost:3000/api/pages", {
-  headers: {
-    Authorization: `${User.slug} API-Key ${YOUR_API_KEY}`,
-  },
-});
-```
-
-Payload ensures that the same, uniform access control is used across all authentication strategies. This enables you to utilize your existing access control configurations with both API keys and the standard email/password authentication. This consistency can aid in maintaining granular control over your API keys.
-
-#### API Key *Only* Authentication
-
-If you want to use API keys as the only authentication method for a collection, you can disable the default local strategy by setting `disableLocalStrategy` to `true` on the collection's `auth` property. This will disable the ability to authenticate with email and password, and will only allow for authentication via API key.
-
-```ts
-import { CollectionConfig } from 'payload/types';
-
-export const Customers: CollectionConfig = {
-  slug: 'customers',
-  auth: {
-    useAPIKey: true,
-    disableLocalStrategy: true,
-  }
-};
-```
-
-### 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.
-
-<Banner type="success">
-  <strong>Tip:</strong>
-  <br />
-  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.
-</Banner>
-
-Example:
-
-```ts
-import { CollectionConfig } from 'payload/types';
-
-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 `
-          <!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>
-        `;
-      }
-      // highlight-end
-    }
-  }
-};
-```
-
-<Banner type="warning">
-  <strong>Important:</strong>
-  <br />
-  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.
-</Banner>
-
-**`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/types';
-
-
-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
-    }
-  }
-};
-```
-
-<Banner type="warning">
-  <strong>Important:</strong>
-  <br />
-  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.
-</Banner>
-
-**`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
-    }
-  }
-}
-```
-
-### Strategies
-
-As of Payload `1.0.0`, you can add additional authentication strategies to Payload easily by passing them to your collection's `auth.strategies` array.
-
-Behind the scenes, Payload uses PassportJS to power its local authentication strategy, so most strategies listed on the PassportJS website will work seamlessly. Combined with adding custom components to the admin panel's `Login` view, you can create advanced authentication strategies directly within Payload.
-
-<Banner type="warning">
-  This is an advanced feature, so only attempt this if you are an experienced
-  developer. Otherwise, just let Payload's built-in authentication handle user
-  auth for you.
-</Banner>
-
-The `strategies` property is an array that takes objects with the following properties:
-
-**`strategy`**
-
-This property can accept a Passport strategy directly, or you can pass a function that takes a `payload` argument, and returns a Passport strategy.
-
-**`name`**
-
-If you pass a strategy to the `strategy` property directly, the `name` property is optional and allows you to override the strategy's built-in name.
-
-However, if you pass a function to `strategy`, `name` is a required property.
-
-In either case, Payload will prefix the strategy name with the collection `slug` that the strategy is passed to.
-
-
-### 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: [ /** */],
-})
-```

package/docs/authentication/operations.mdx

@@ -1,388 +0,0 @@
----
-title: Authentication Operations
-label: Operations
-order: 30
-desc: Enabling Authentication automatically makes key operations available such as Login, Logout, Verify, Unlock, Reset Password and more.
-keywords: authentication, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-Enabling Authentication on a Collection automatically exposes additional auth-based operations in the Local, REST, and GraphQL APIs.
-
-### Access
-
-The Access operation returns what a logged in user can and can't do with the collections and globals that are registered via your config. This data can be immensely helpful if your app needs to show and hide certain features based on access control, as the Payload Admin panel does.
-
-**REST API endpoint**:
-
-`GET http://localhost:3000/api/access`
-
-Example response:
-```ts
-{
-  canAccessAdmin: true,
-  collections: {
-    pages: {
-      create: {
-        permission: true,
-      },
-      read: {
-        permission: true,
-      },
-      update: {
-        permission: true,
-      },
-      delete: {
-        permission: true,
-      },
-      fields: {
-        title: {
-          create: {
-            permission: true,
-          },
-          read: {
-            permission: true,
-          },
-          update: {
-            permission: true,
-          },
-        }
-      }
-    }
-  }
-}
-```
-
-**Example GraphQL Query**:
-
-```graphql
-query {
-  Access {
-    pages {
-      read {
-        permission
-      }
-    }
-  }
-}
-```
-
-Document access can also be queried on a collection/global basis. Access on a global can queried like `http://localhost:3000/api/global-slug/access`, Collection document access can be queried like `http://localhost:3000/api/collection-slug/access/:id`.
-
-### Me
-
-Returns either a logged in user with token or null when there is no logged in user.
-
-**REST API endpoint**:
-
-`GET http://localhost:3000/api/[collection-slug]/me`
-
-Example response:
-```ts
-{
-  user: { // The JWT "payload" ;) from the logged in user
-    email: 'dev@payloadcms.com',
-    createdAt: "2020-12-27T21:16:45.645Z",
-    updatedAt: "2021-01-02T18:37:41.588Z",
-    id: "5ae8f9bde69e394e717c8832"
-  },
-  token: '34o4345324...', // The token that can be used to authenticate the user
-  exp: 1609619861, // Unix timestamp representing when the user's token will expire
-}
-```
-
-**Example GraphQL Query**:
-
-```graphql
-query {
-  me[collection-singular-label] {
-    user {
-      email
-    }
-    exp
-  }
-}
-```
-
-### Login
-
-Accepts an `email` and `password`. On success, it will return the logged in user as well as a token that can be used to authenticate. In the GraphQL and REST APIs, this operation also automatically sets an HTTP-only cookie including the user's token. If you pass an Express `res` to the Local API operation, Payload will set a cookie there as well.
-
-**Example REST API login**:
-```ts
-const res = await fetch('http://localhost:3000/api/[collection-slug]/login', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    email: 'dev@payloadcms.com',
-    password: 'this-is-not-our-password...or-is-it?',
-  })
-})
-
-const json = await res.json();
-
-// JSON will be equal to the following:
-/*
-{
-  user: {
-    email: 'dev@payloadcms.com',
-    createdAt: "2020-12-27T21:16:45.645Z",
-    updatedAt: "2021-01-02T18:37:41.588Z",
-    id: "5ae8f9bde69e394e717c8832"
-  },
-  token: '34o4345324...',
-  exp: 1609619861
-}
-*/
-```
-
-**Example GraphQL Mutation**:
-
-```graphql
-mutation {
-  login[collection-singular-label](email: "dev@payloadcms.com", password: "yikes") {
-    user {
-      email
-    }
-    exp
-    token
-  }
-}
-```
-
-**Example Local API login**:
-
-```ts
-const result = await payload.login({
-  collection: '[collection-slug]',
-  data: {
-    email: 'dev@payloadcms.com',
-    password: 'get-out',
-  },
-})
-```
-
-### Logout
-
-As Payload sets HTTP-only cookies, logging out cannot be done by just removing a cookie in JavaScript, as HTTP-only cookies are inaccessible by JS within the browser. So, Payload exposes a `logout` operation to delete the token in a safe way.
-
-**Example REST API logout**:
-```ts
-const res = await fetch('http://localhost:3000/api/[collection-slug]/logout', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-})
-```
-
-**Example GraphQL Mutation**:
-
-```
-mutation {
-  logout[collection-singular-label]
-}
-```
-
-### Refresh
-
-Allows for "refreshing" JWTs. If your user has a token that is about to expire, but the user is still active and using the app, you might want to use the `refresh` operation to receive a new token by sending the operation the token that is about to expire.
-
-This operation requires a non-expired token to send back a new one. If the user's token has already expired, you will need to allow them to log in again to retrieve a new token.
-
-If successful, this operation will automatically renew the user's HTTP-only cookie and will send back the updated token in JSON.
-
-**Example REST API token refresh**:
-```ts
-const res = await fetch('http://localhost:3000/api/[collection-slug]/refresh-token', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-})
-
-const json = await res.json();
-
-// JSON will be equal to the following:
-/*
-{
-  user: {
-    email: 'dev@payloadcms.com',
-    createdAt: "2020-12-27T21:16:45.645Z",
-    updatedAt: "2021-01-02T18:37:41.588Z",
-    id: "5ae8f9bde69e394e717c8832"
-  },
-  refreshedToken: '34o4345324...',
-  exp: 1609619861
-}
-*/
-```
-
-**Example GraphQL Mutation**:
-
-```
-mutation {
-  refreshToken[collection-singular-label] {
-    user {
-      email
-    }
-    refreshedToken
-  }
-}
-```
-
-<Banner type="success">
-  The Refresh operation will automatically find the user's token in either a JWT header or the HTTP-only cookie. But, you can specify the token you're looking to refresh by providing the REST API with a `token` within the JSON body of the request, or by providing the GraphQL resolver a `token` arg.
-</Banner>
-
-### Verify by Email
-
-If your collection supports email verification, the Verify operation will be exposed which accepts a verification token and sets the user's `_verified` property to `true`, thereby allowing the user to authenticate with the Payload API.
-
-**Example REST API user verification**:
-```ts
-const res = await fetch(`http://localhost:3000/api/[collection-slug]/verify/${TOKEN_HERE}`, {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-});
-```
-
-**Example GraphQL Mutation**:
-
-```graphql
-mutation {
-  verifyEmail[collection-singular-label](token: "TOKEN_HERE")
-}
-```
-
-**Example Local API verification**:
-
-```ts
-const result = await payload.verifyEmail({
-  collection: '[collection-slug]',
-  token: 'TOKEN_HERE',
-})
-```
-
-### Unlock
-
-If a user locks themselves out and you wish to deliberately unlock them, you can utilize the Unlock operation. The Admin panel features an Unlock control automatically for all collections that feature max login attempts, but you can programmatically unlock users as well by using the Unlock operation.
-
-To restrict who is allowed to unlock users, you can utilize the [`unlock`](/docs/access-control/overview#unlock) access control function.
-
-**Example REST API unlock**:
-```ts
-const res = await fetch(`http://localhost:3000/api/[collection-slug]/unlock`, {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-})
-```
-
-**Example GraphQL Mutation**:
-
-```
-mutation {
-  unlock[collection-singular-label]
-}
-```
-
-**Example Local API unlock**:
-
-```ts
-const result = await payload.unlock({
-  collection: '[collection-slug]',
-})
-```
-
-### Forgot Password
-
-Payload comes with built-in forgot password functionality. Submitting an email address to the Forgot Password operation will generate an email and send it to the respective email address with a link to reset their password.
-
-The link to reset the user's password contains a token which is what allows the user to securely reset their password.
-
-By default, the Forgot Password operations send users to the Payload Admin panel to reset their password, but you can customize the generated email to send users to the frontend of your app instead by [overriding the email HTML](/docs/authentication/config#forgot-password).
-
-**Example REST API Forgot Password**:
-```ts
-const res = await fetch(`http://localhost:3000/api/[collection-slug]/forgot-password`, {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    email: 'dev@payloadcms.com',
-  }),
-});
-```
-
-**Example GraphQL Mutation**:
-
-```
-mutation {
-  forgotPassword[collection-singular-label](email: "dev@payloadcms.com")
-}
-```
-
-**Example Local API forgot password**:
-
-```ts
-const token = await payload.forgotPassword({
-  collection: '[collection-slug]',
-  data: {
-    email: 'dev@payloadcms.com',
-  },
-  disableEmail: false // you can disable the auto-generation of email via local API
-});
-```
-
-<Banner type="success">
-  <strong>Tip:</strong><br/>
-  You can stop the reset-password email from being sent via using the local API. This is helpful if you need to create user accounts programmatically, but not set their password for them. This effectively generates a reset password token which you can then use to send to a page you create, allowing a user to "complete" their account by setting their password. In the background, you'd use the token to "reset" their password.
-</Banner>
-
-### Reset Password
-
-After a user has "forgotten" their password and a token is generated, that token can be used to send to the reset password operation along with a new password which will allow the user to reset their password securely.
-
-**Example REST API Reset Password**:
-```ts
-const res = await fetch(`http://localhost:3000/api/[collection-slug]/reset-password`, {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    token: 'TOKEN_GOES_HERE'
-    password: 'not-today',
-  }),
-});
-
-const json = await res.json();
-
-// JSON will be equal to the following:
-/*
-{
-  user: {
-    email: 'dev@payloadcms.com',
-    createdAt: "2020-12-27T21:16:45.645Z",
-    updatedAt: "2021-01-02T18:37:41.588Z",
-    id: "5ae8f9bde69e394e717c8832"
-  },
-  token: '34o4345324...',
-  exp: 1609619861
-}
-*/
-```
-
-**Example GraphQL Mutation**:
-
-```graphql
-mutation {
-  resetPassword[collection-singular-label](token: "TOKEN_GOES_HERE", password: "not-today")
-}
-```