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
2024-10-07 08:04:01 +00:00
parent adb3a8246a
commit 781d0ca624
38 changed files with 1479 additions and 40 deletions
@@ -22,6 +22,9 @@
 *         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
@@ -0,0 +1,60 @@
+/**
+ * @oas [post] /auth/user/{auth_provider}/reset-password
+ * 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:  |-
+ *       curl -X POST '{backend_url}/auth/user/emailpass/reset-password' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "identifier": "admin@medusa-test.com"
+ *       }'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "201":
+ *     description: OK
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ * x-workflow: generateResetPasswordTokenWorkflow
+ * 
+*/
+
@@ -0,0 +1,76 @@
+/**
+ * @oas [post] /auth/user/{auth_provider}/update
+ * 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:  |-
+ *       curl -X POST '{backend_url}/auth/user/emailpass/update?token=123' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "admin@medusa-test.com",
+ *         "password": "supersecret"
+ *       }'
+ * 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"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ * 
+*/
+