diff --git a/idn/beta/paths/query-password-info.yaml b/idn/beta/paths/query-password-info.yaml
index b9f4424..12e9ffd 100644
--- a/idn/beta/paths/query-password-info.yaml
+++ b/idn/beta/paths/query-password-info.yaml
@@ -5,7 +5,15 @@ post:
   summary: Query Password Info
 #  security:
 #   - oauth2: [API]
-  description: This API is used to query password related information. A token with API authority is required to call this API.
+  description: |
+    This API is used to query password related information. 
+    
+    A token with [API authority](https://developer.sailpoint.com/idn/api/authentication#client-credentials-grant-flow) 
+    is required to call this API.  "API authority" refers to a token that only has the "client_credentials" 
+    grant type, and therefore no user context. A [personal access token](https://developer.sailpoint.com/idn/api/authentication#personal-access-tokens) 
+    or a token generated with the [authorization_code](https://developer.sailpoint.com/idn/api/authentication#authorization-code-grant-flow) 
+    grant type will **NOT** work on this endpoint, and a `403 Forbidden` response 
+    will be returned.
   requestBody:
     required: true
     content:
@@ -44,7 +52,11 @@ post:
             }
     '400':
       $ref: '../../v3/responses/400.yaml'
+    '401':
+      $ref: '../../v3/responses/401.yaml'
     '403':
       $ref: '../../v3/responses/403.yaml'
+    '429':
+      $ref: '../../v3/responses/429.yaml'
     '500':
       $ref: '../../v3/responses/500.yaml'
\ No newline at end of file
diff --git a/idn/beta/paths/set-password.yaml b/idn/beta/paths/set-password.yaml
index 4a6e765..36103fa 100644
--- a/idn/beta/paths/set-password.yaml
+++ b/idn/beta/paths/set-password.yaml
@@ -3,7 +3,12 @@ post:
   tags:
     - Password Management
   summary: Set Identity's Password
-  description: This API is used to set a password for an identity. The password can only be set by the actual identity owner or by a trusted API client application.
+  description: |
+    This API is used to set a password for an identity. 
+    
+    An identity can change their own password if they use a token generated by their IDN user, such as a [personal access token](https://developer.sailpoint.com/idn/api/authentication#personal-access-tokens) or ["authorization_code" derived OAuth token](https://developer.sailpoint.com/idn/api/authentication#authorization-code-grant-flow).
+    
+    A token with [API authority](https://developer.sailpoint.com/idn/api/authentication#client-credentials-grant-flow) can be used to change **any** identity's password.  "API authority" refers to a token that only has the "client_credentials" grant type.
   requestBody:
     required: true
     content:
@@ -37,5 +42,7 @@ post:
       $ref: '../../v3/responses/401.yaml'
     '403':
       $ref: '../../v3/responses/403.yaml'
+    '429':
+      $ref: '../../v3/responses/429.yaml'
     '500':
       $ref: '../../v3/responses/500.yaml'
\ No newline at end of file
diff --git a/idn/v3/paths/set-password.yaml b/idn/v3/paths/set-password.yaml
index f0b473d..bb98f6e 100644
--- a/idn/v3/paths/set-password.yaml
+++ b/idn/v3/paths/set-password.yaml
@@ -3,7 +3,12 @@ post:
   tags:
     - Password Management
   summary: Set Identity's Password
-  description: This API is used to set a password for an identity. The password can only be set by the actual identity owner or by a trusted API client application.
+  description: |
+    This API is used to set a password for an identity. 
+    
+    An identity can change their own password if they use a token generated by their IDN user, such as a [personal access token](https://developer.sailpoint.com/idn/api/authentication#personal-access-tokens) or ["authorization_code" derived OAuth token](https://developer.sailpoint.com/idn/api/authentication#authorization-code-grant-flow).
+    
+    A token with [API authority](https://developer.sailpoint.com/idn/api/authentication#client-credentials-grant-flow) can be used to change **any** identity's password.  "API authority" refers to a token that only has the "client_credentials" grant type.
   requestBody:
     required: true
     content: