From e80da7cb757eaa1e74c1c959c4ca96a6e8c7ffb7 Mon Sep 17 00:00:00 2001
From: Paul <paul@payloadcms.com>
Date: Thu, 5 Sep 2024 18:04:13 -0600
Subject: [PATCH] chore: add jsdocs for authentication types and add missing
 config to docs (#8082)

---
 docs/authentication/overview.mdx   |  1 +
 packages/payload/src/auth/types.ts | 46 ++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdx
index e1c402949..2f9dbb30e 100644
--- a/docs/authentication/overview.mdx
+++ b/docs/authentication/overview.mdx
@@ -85,6 +85,7 @@ The following options are available:
 | **`lockTime`**             | Set the time (in milliseconds) that a user should be locked out if they fail authentication more times than `maxLoginAttempts` allows for.                                                                                          |
 | **`loginWithUsername`**    | Ability to allow users to login with username/password. [More](/docs/authentication/overview#login-with-username)                                                                                                                     |
 | **`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.                                                                       |
+| **`removeTokenFromResponses`** | Set to true if you want to remove the token from the returned authentication API responses such as login or refresh.                                                                                                                                                            |
 | **`strategies`**           | Advanced - an array of custom authentification strategies to extend this collection's authentication with. [More details](./custom-strategies).                                                                         |
 | **`tokenExpiration`**      | How long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time.                                                                                                                     |
 | **`useAPIKey`**            | Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. [More details](./api-keys).                                                                       |
diff --git a/packages/payload/src/auth/types.ts b/packages/payload/src/auth/types.ts
index b15d7f9d5..ca62348cd 100644
--- a/packages/payload/src/auth/types.ts
+++ b/packages/payload/src/auth/types.ts
@@ -132,24 +132,70 @@ export type LoginWithUsernameOptions =
     }
 
 export interface IncomingAuthType {
+  /**
+   * Set cookie options, including secure, sameSite, and domain. For advanced users.
+   */
   cookies?: {
     domain?: string
     sameSite?: 'Lax' | 'None' | 'Strict' | boolean
     secure?: boolean
   }
+  /**
+   * 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.
+   * @default 0
+   */
   depth?: number
+  /**
+   * Advanced - disable Payload's built-in local auth strategy. Only use this property if you have replaced Payload's auth mechanisms with your own.
+   */
   disableLocalStrategy?: true
+  /**
+   * Customize the way that the forgotPassword operation functions.
+   * @link https://payloadcms.com/docs/beta/authentication/email#forgot-password
+   */
   forgotPassword?: {
     generateEmailHTML?: GenerateForgotPasswordEmailHTML
     generateEmailSubject?: GenerateForgotPasswordEmailSubject
   }
+  /**
+   * Set the time (in milliseconds) that a user should be locked out if they fail authentication more times than maxLoginAttempts allows for.
+   */
   lockTime?: number
+  /**
+   * Ability to allow users to login with username/password.
+   *
+   * @link https://payloadcms.com/docs/beta/authentication/overview#login-with-username
+   */
   loginWithUsername?: boolean | LoginWithUsernameOptions
+  /**
+   * 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.
+   */
   maxLoginAttempts?: number
+  /***
+   * Set to true if you want to remove the token from the returned authentication API responses such as login or refresh.
+   */
   removeTokenFromResponses?: true
+  /**
+   * Advanced - an array of custom authentification strategies to extend this collection's authentication with.
+   * @link https://payloadcms.com/docs/beta/authentication/custom-strategies
+   */
   strategies?: AuthStrategy[]
+  /**
+   * Controls how many seconds the token will be valid for. Default is 2 hours.
+   * @default 7200
+   * @link https://payloadcms.com/docs/beta/authentication/overview#config-options
+   */
   tokenExpiration?: number
+  /**
+   * Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection.
+   * @default false
+   * @link https://payloadcms.com/docs/beta/authentication/api-keys
+   */
   useAPIKey?: boolean
+  /**
+   * 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.
+   * @link https://payloadcms.com/docs/beta/authentication/email#email-verification
+   */
   verify?:
     | {
         generateEmailHTML?: GenerateVerifyEmailHTML