docs: updates following authentication flow changes (#8706)

* docs: updates following authentication flow changes

* generate sidebar

* added open api specs

* fix up OAS

* changes to existing pages

* change sidebar items

* update marketplace recipe

www/utils/generated/oas-output/base/admin.oas.base.yaml

@@ -6,6 +6,9 @@ info:
     name: MIT
     url: https://github.com/medusajs/medusa/blob/master/LICENSE
 tags:
+  - name: Auth
+    description: >
+      Auth API routes allow you to manage an admin user's authentication.
   - name: Api Keys
   - name: Campaigns
   - name: Claims

www/utils/generated/oas-output/base/store.oas.base.yaml

@@ -6,6 +6,9 @@ info:
     name: MIT
     url: https://github.com/medusajs/medusa/blob/master/LICENSE
 tags:
+  - name: Auth
+    description: >
+      Auth API routes allow you to manage a customer's authentication.
   - name: Carts
     description: >
       A cart is a virtual shopping bag that customers can use to add items they

www/utils/generated/oas-output/operations/admin/delete_auth_session.ts

@@ -0,0 +1,44 @@
+/**
+ * @oas [delete] /auth/session
+ * operationId: DeleteSession
+ * summary: Delete Authentication Session
+ * description: Deletes the cookie session ID previously set for authentication.
+ * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |-
+ *       curl -X DELETE '{backend_url}/auth/session' \
+ *       -H 'Cookie: connect.sid={sid}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           description: SUMMARY
+ *           required:
+ *             - success
+ *           properties:
+ *             success:
+ *               type: boolean
+ *               title: success
+ *               description: Whether the session was deleted 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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider].ts

@@ -0,0 +1,42 @@
+/**
+ * @oas [post] /auth/user/{auth_provider}
+ * operationId: PostActor_typeAuth_provider
+ * summary: Authenticate User
+ * description: Authenticate an admin user and receive the JWT token to be used in the header of subsequent requests.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/user/{auth_provider}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_callback.ts

@@ -0,0 +1,43 @@
+/**
+ * @oas [post] /auth/user/{auth_provider}/callback
+ * operationId: PostActor_typeAuth_providerCallback
+ * summary: Validate Authentication Callback
+ * description: Third-party authentication providers, such as Google, require an API route to call once authentication with the third-party provider is finished.
+ *   This API route validates callback for admin users logged-in with third-party providers.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "google"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/user/{auth_provider}/callback'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_register.ts

@@ -0,0 +1,43 @@
+/**
+ * @oas [post] /auth/user/{auth_provider}/register
+ * operationId: PostActor_typeAuth_provider_register
+ * summary: Retrieve Registration JWT Token
+ * description: A registration JWT token is used in the header of requests that create a user, such as the accept invitation request.
+ *   This API route retrieves the JWT token of a user that hasn't been registered yet.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/user/{auth_provider}/register'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/admin/post_auth_session.ts

@@ -0,0 +1,37 @@
+/**
+ * @oas [post] /auth/session
+ * operationId: PostSession
+ * summary: Set Authentication Session
+ * description: Set the cookie session ID of an admin user. The admin must be previously authenticated with the `/auth/user/{provider}` API route first,
+ *   as the JWT token is required in the header of the request.
+ * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |-
+ *       curl -X POST '{backend_url}/auth/session' \
+ *       -H 'Authorization: Bearer {jwt_token}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthAdminSessionResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/delete_auth_session.ts

@@ -0,0 +1,44 @@
+/**
+ * @oas [delete] /auth/session
+ * operationId: DeleteSession
+ * summary: Delete Authentication Session
+ * description: Deletes the cookie session ID previously set for authentication.
+ * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |-
+ *       curl -X DELETE '{backend_url}/auth/session' \
+ *       -H 'Cookie: connect.sid={sid}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           description: SUMMARY
+ *           required:
+ *             - success
+ *           properties:
+ *             success:
+ *               type: boolean
+ *               title: success
+ *               description: Whether the session was deleted 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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider].ts

@@ -0,0 +1,42 @@
+/**
+ * @oas [post] /auth/customer/{auth_provider}
+ * operationId: PostActor_typeAuth_provider
+ * summary: Authenticate Customer
+ * description: Authenticate a customer and receive the JWT token to be used in the header of subsequent requests.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/customer/{auth_provider}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_callback.ts

@@ -0,0 +1,43 @@
+/**
+ * @oas [post] /auth/customer/{auth_provider}/callback
+ * operationId: PostActor_typeAuth_providerCallback
+ * summary: Validate Authentication Callback
+ * description: Third-party authentication providers, such as Google, require an API route to call once authentication with the third-party provider is finished.
+ *   This API route validates callback for customers logged-in with third-party providers.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "google"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/customer/{auth_provider}/callback'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_register.ts

@@ -0,0 +1,43 @@
+/**
+ * @oas [post] /auth/customer/{auth_provider}/register
+ * operationId: PostActor_typeAuth_provider_register
+ * summary: Retrieve Registration JWT Token
+ * description: A registration JWT token is used in the header of requests that create a customer.
+ *   This API route retrieves the JWT token of a customer that hasn't been registered yet.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/customer/{auth_provider}/register'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/post_auth_session.ts

@@ -0,0 +1,37 @@
+/**
+ * @oas [post] /auth/session
+ * operationId: PostSession
+ * summary: Set Authentication Session
+ * description: 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.
+ * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |-
+ *       curl -X POST '{backend_url}/auth/session' \
+ *       -H 'Authorization: Bearer {jwt_token}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthStoreSessionResponse"
+ *   "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"
+ * 
+*/
+

www/utils/generated/oas-output/schemas/AuthAdminSessionResponse.ts

@@ -0,0 +1,14 @@
+/**
+ * @schema AuthAdminSessionResponse
+ * type: object
+ * description: The authenticated user's details.
+ * x-schemaName: AuthAdminSessionResponse
+ * required:
+ *   - user
+ * properties:
+ *   user:
+ *     title: user
+ *     description: The logged-in user.
+ *     $ref: "#/components/schemas/AdminUser"
+*/
+

www/utils/generated/oas-output/schemas/AuthResponse.ts

@@ -0,0 +1,14 @@
+/**
+ * @schema AuthResponse
+ * type: object
+ * description: The authentication's details.
+ * x-schemaName: AuthResponse
+ * required:
+ *   - token
+ * properties:
+ *   token:
+ *     type: string
+ *     title: token
+ *     description: The JWT token used for registration or authentication.
+*/
+

www/utils/generated/oas-output/schemas/AuthStoreSessionResponse.ts

@@ -0,0 +1,14 @@
+/**
+ * @schema AuthStoreSessionResponse
+ * type: object
+ * description: The authenticated customer's details.
+ * x-schemaName: AuthStoreSessionResponse
+ * required:
+ *   - user
+ * properties:
+ *   user:
+ *     title: user
+ *     description: The logged-in customer.
+ *     $ref: "#/components/schemas/StoreCustomer"
+*/
+