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 11:04:01 +03:00
parent adb3a8246a
commit 781d0ca624
38 changed files with 1479 additions and 40 deletions
--- a/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}.yaml
+++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}.yaml
@@ -11,8 +11,8 @@ post:
    continue authentication with the third-party service.
  externalDocs:
    url: >-
-      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#types-of-authentication-flows
-    description: Learn about different authentication flows.
+      https://docs.medusajs.com/v2/storefront-development/customers/login#1-using-a-jwt-token
+    description: 'Storefront development: How to login as a customer'
  x-authenticated: false
  parameters:
    - name: auth_provider
--- a/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_callback.yaml
+++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_callback.yaml
@@ -17,8 +17,8 @@ post:
    in the request's Authorization header.
  externalDocs:
    url: >-
-      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow
-    description: Learn about third-party authentication flow.
+      https://docs.medusajs.com/v2/storefront-development/customers/third-party-login
+    description: 'Storefront development: Implement third-party (social) login.'
  x-authenticated: false
  parameters:
    - name: auth_provider
--- a/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_register.yaml
+++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_register.yaml
@@ -6,9 +6,8 @@ post:
    been registered yet. The token is used in the header of requests that create
    a customer.
  externalDocs:
-    url: >-
-      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#1-basic-authentication-flow
-    description: Learn about the basic authentication flow.
+    url: https://docs.medusajs.com/v2/storefront-development/customers/register
+    description: 'Storefront development: How to register a customer'
  x-authenticated: false
  parameters:
    - name: auth_provider
@@ -27,6 +26,9 @@ post:
          description: >-
            The input data necessary for authentication. For example, for
            email-pass authentication, pass `email` and `password` properties.
+          example:
+            email: customer@gmail.com
+            password: supersecret
  x-codeSamples:
    - lang: Shell
      label: cURL
--- a/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_reset-password.yaml
+++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_reset-password.yaml
@@ -0,0 +1,60 @@
+post:
+  operationId: PostActor_typeAuth_providerResetPassword
+  summary: Generate Reset Password Token for Customer
+  x-sidebar-summary: Generate Reset Password Token
+  description: >
+    Generate a reset password token for a customer. This API route emits the
+    `auth.password_reset` 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/storefront-development/customers/reset-password#1-request-reset-password-page
+    description: 'Storefront development: How to create the request reset password page.'
+  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 customer's identifier for the selected auth provider. For
+            example, for the `emailpass` auth provider, the value is the
+            customer's email.
+          example: customer@gmail.com
+  x-codeSamples:
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: >-
+          ../code_samples/Shell/auth_customer_{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
--- a/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_update.yaml
+++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_update.yaml
@@ -0,0 +1,75 @@
+post:
+  operationId: PostActor_typeAuth_providerUpdate
+  summary: Reset a Customer's Password
+  x-sidebar-summary: Reset Password
+  description: >-
+    Reset a customer's password. Generate the reset password token first using
+    the Get Reset Password Token API route.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#2-reset-password-page
+    description: 'Storefront development: How to create the reset password page.'
+  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 with the specified auth
+            provider. For example, for email-pass authentication, pass `email`
+            and `password` properties.
+          example:
+            email: customer@gmail.com
+            password: supersecret
+  x-codeSamples:
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/auth_customer_{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
--- a/www/apps/api-reference/specs/store/paths/auth_session.yaml
+++ b/www/apps/api-reference/specs/store/paths/auth_session.yaml
@@ -5,6 +5,10 @@ post:
    Set the cookie session ID of a customer. The customer must be previously
    authenticated with the `/auth/customer/{provider}` API route first, as the
    JWT token is required in the header of the request.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/storefront-development/customers/login#2-using-a-cookie-session
+    description: 'Storefront development: How to login as a customer'
  x-authenticated: true
  x-codeSamples:
    - lang: Shell
--- a/www/apps/api-reference/specs/store/paths/auth_token_refresh.yaml
+++ b/www/apps/api-reference/specs/store/paths/auth_token_refresh.yaml
@@ -8,8 +8,8 @@ post:
    every day.
  externalDocs:
    url: >-
-      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow
-    description: Learn about third-party authentication flow.
+      https://docs.medusajs.com/v2/storefront-development/customers/third-party-login
+    description: 'Storefront development: Implement third-party (social) login.'
  x-authenticated: true
  x-codeSamples:
    - lang: Shell