docs: added docs for reset password (#9306)

- Added to docs on implementing auth flows using the module and API routes how to update a user's password
- Added guide on how to send a notification when a password token is generated
- Added a guide on implementing reset password flow in storefront
- Added OAS for the `/update` and `/reset-password` routes + generated specs for the API reference

www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_register.yaml

@@ -27,6 +27,9 @@ post:
           description: >-
             The input data necessary for authentication. For example, for
             email-pass authentication, pass `email` and `password` properties.
+          example:
+            email: admin@medusa-test.com
+            password: supersecret
   x-codeSamples:
     - lang: Shell
       label: cURL

www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_reset-password.yaml

@@ -0,0 +1,58 @@
+post:
+  operationId: PostActor_typeAuth_providerResetPassword
+  summary: Generate Reset Password Token for Admin User
+  x-sidebar-summary: Generate Reset Password Token
+  description: >
+    Generate a reset password token for an admin user. This API route emits the
+    `` event, passing it the token as a payload. You can listen to that event
+    and send the user a notification. The notification should have a URL that
+    accepts a `token` query parameter.
+
+
+     Use the generated token to update the user's password using the Reset Password API route.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#generate-reset-password-token-route
+    description: Learn more about this API route.
+  x-authenticated: false
+  parameters:
+    - name: auth_provider
+      in: path
+      description: The provider used for authentication.
+      required: true
+      schema:
+        type: string
+        example: emailpass
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          title: identifier
+          description: >-
+            The user's identifier for the selected auth provider. For example,
+            for the `emailpass` auth provider, the value is the user's email.
+          example: admin@medusa-test.com
+  x-codeSamples:
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/auth_user_{auth_provider}_reset-password/post.sh
+  tags:
+    - Auth
+  responses:
+    '201':
+      description: OK
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '401':
+      $ref: ../components/responses/unauthorized.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml
+  x-workflow: generateResetPasswordTokenWorkflow

www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_update.yaml

@@ -0,0 +1,74 @@
+post:
+  operationId: PostActor_typeAuth_providerUpdate
+  summary: Reset an Admin User's Password
+  x-sidebar-summary: Reset Password
+  description: >-
+    Reset a user's password. Generate the reset password token first using the
+    Get Reset Password Token API route.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#reset-password-route
+    description: Learn more about this API route.
+  x-authenticated: false
+  parameters:
+    - name: auth_provider
+      in: path
+      description: The provider used for authentication.
+      required: true
+      schema:
+        type: string
+        example: emailpass
+    - name: token
+      in: query
+      description: >-
+        The reset password token received using the Get Reset Password API
+        route.
+      required: true
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          title: input
+          description: >-
+            The input data necessary for authentication. For example, for
+            email-pass authentication, pass `email` and `password` properties.
+          example:
+            email: admin@medusa-test.com
+            password: supersecret
+  x-codeSamples:
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/auth_user_{auth_provider}_update/post.sh
+  tags:
+    - Auth
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - success
+            description: Details on the reset password's status.
+            properties:
+              success:
+                type: boolean
+                title: success
+                description: Whether the password was reset successfully.
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '401':
+      $ref: ../components/responses/unauthorized.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml