diff --git a/packages/cli/oas/medusa-oas-cli/redocly/redocly-config.yaml b/packages/cli/oas/medusa-oas-cli/redocly/redocly-config.yaml index e34435195a..1e49ac3858 100644 --- a/packages/cli/oas/medusa-oas-cli/redocly/redocly-config.yaml +++ b/packages/cli/oas/medusa-oas-cli/redocly/redocly-config.yaml @@ -1,8 +1,5 @@ plugins: - - "./plugins/medusa/index.js" - -# Allows to replace a $ref with `type: object` in order to avoid infinite loops -# when Redocly attempts to render circular references. + - ./plugins/medusa/index.js decorators: medusa/circular-patch: schemas: @@ -41,19 +38,19 @@ decorators: - AdminFulfillmentSet OrderTransaction: - Order - -# Similar config to /www/docs/docusaurus.config.js > redocusaurus -# Allows to emulate rendering of API public documentation when using `yarn redocly preview-docs openapi.yaml` + AdminTaxRegion: + - AdminTaxRegion + - AdminTaxRate theme: openapi: theme: colors: primary: - dark: "#242526" + dark: '#242526' sidebar: - width: "250px" + width: 250px disableSearch: true - expandResponses: "200,204" + expandResponses: 200,204 generatedPayloadSamplesMaxDepth: 4 hideDownloadButton: true hideRequestPayloadSample: true diff --git a/www/apps/api-reference/app/_mdx/admin.mdx b/www/apps/api-reference/app/_mdx/admin.mdx index 8cdab71890..4bb62b8419 100644 --- a/www/apps/api-reference/app/_mdx/admin.mdx +++ b/www/apps/api-reference/app/_mdx/admin.mdx @@ -34,7 +34,7 @@ All API Routes are prefixed with `/admin`. So, during development, the API Route ## Authentication -There are three ways to send authenticated requests to the Medusa server: Using an admin user's API token, using a JWT token in a bearer authorization header, or using a cookie session ID. +There are three ways to send authenticated requests to the Medusa server: Using a JWT token in a bearer authorization header, using an admin user's API token, or using a cookie session ID. ### Bearer Authorization with JWT Tokens @@ -42,8 +42,6 @@ Use a JWT token in a request's bearer authorization header to send authenticated #### How to Obtain the JWT Token -{/* TODO add correct link to auth route */} - JWT tokens are obtained by sending a request to the authentication route passing it the user's email and password in the request body. For example: @@ -59,6 +57,8 @@ curl -X POST '{backend_url}/auth/user/emailpass' \ If authenticated successfully, an object is returned in the response with the property `token` being the JWT token. +Learn more about the authentication route [here](#auth_postactor_typeauth_provider) + #### How to Use the JWT Token Pass the JWT token in the authorization bearer header: diff --git a/www/apps/api-reference/app/_mdx/store.mdx b/www/apps/api-reference/app/_mdx/store.mdx index 4cb87c070d..72a6cf0b99 100644 --- a/www/apps/api-reference/app/_mdx/store.mdx +++ b/www/apps/api-reference/app/_mdx/store.mdx @@ -43,8 +43,6 @@ Use a JWT token in a request's bearer authorization header to send authenticated #### How to Obtain the JWT Token -{/* TODO add correct link to auth route */} - JWT tokens are obtained by sending a request to the authentication route passing it the customer's email and password in the request body. For example: @@ -58,16 +56,10 @@ curl -X POST '{backend_url}/auth/customer/emailpass' \ }' ``` - - -{/* TODO add link to implementing login with google guide. */} - -Alternatively, you can use the `google` provider instead of `emailpass`. - - - If authenticated successfully, an object is returned in the response with the property `token` being the JWT token. +Learn more about the authentication route [here](#auth_postactor_typeauth_provider) + #### How to Use the JWT Token Pass the JWT token in the authorization bearer header: diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/delete.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/delete.sh new file mode 100644 index 0000000000..cca69225d8 --- /dev/null +++ b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/delete.sh @@ -0,0 +1,2 @@ +curl -X DELETE '{backend_url}/auth/session' \ +-H 'Cookie: connect.sid={sid}' \ No newline at end of file diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/post.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/post.sh new file mode 100644 index 0000000000..fc9cc81528 --- /dev/null +++ b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/post.sh @@ -0,0 +1,2 @@ +curl -X POST '{backend_url}/auth/session' \ +-H 'Authorization: Bearer {jwt_token}' \ No newline at end of file diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}/post.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}/post.sh new file mode 100644 index 0000000000..cceca04346 --- /dev/null +++ b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}/post.sh @@ -0,0 +1 @@ +curl -X POST '{backend_url}/auth/user/{auth_provider}' \ No newline at end of file diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_callback/post.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_callback/post.sh new file mode 100644 index 0000000000..4be8f2007d --- /dev/null +++ b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_callback/post.sh @@ -0,0 +1 @@ +curl -X POST '{backend_url}/auth/user/{auth_provider}/callback' \ No newline at end of file diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_register/post.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_register/post.sh new file mode 100644 index 0000000000..996baeeae5 --- /dev/null +++ b/www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_register/post.sh @@ -0,0 +1 @@ +curl -X POST '{backend_url}/auth/user/{auth_provider}/register' \ No newline at end of file diff --git a/www/apps/api-reference/specs/admin/components/schemas/AuthAdminSessionResponse.yaml b/www/apps/api-reference/specs/admin/components/schemas/AuthAdminSessionResponse.yaml new file mode 100644 index 0000000000..00217cd800 --- /dev/null +++ b/www/apps/api-reference/specs/admin/components/schemas/AuthAdminSessionResponse.yaml @@ -0,0 +1,10 @@ +type: object +description: The authenticated user's details. +x-schemaName: AuthAdminSessionResponse +required: + - user +properties: + user: + title: user + description: The logged-in user. + $ref: ./AdminUser.yaml diff --git a/www/apps/api-reference/specs/admin/components/schemas/AuthResponse.yaml b/www/apps/api-reference/specs/admin/components/schemas/AuthResponse.yaml new file mode 100644 index 0000000000..68386983f7 --- /dev/null +++ b/www/apps/api-reference/specs/admin/components/schemas/AuthResponse.yaml @@ -0,0 +1,10 @@ +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. diff --git a/www/apps/api-reference/specs/admin/components/schemas/AuthStoreSessionResponse.yaml b/www/apps/api-reference/specs/admin/components/schemas/AuthStoreSessionResponse.yaml new file mode 100644 index 0000000000..3ec7c5c8a0 --- /dev/null +++ b/www/apps/api-reference/specs/admin/components/schemas/AuthStoreSessionResponse.yaml @@ -0,0 +1,10 @@ +type: object +description: The authenticated customer's details. +x-schemaName: AuthStoreSessionResponse +required: + - user +properties: + user: + title: user + description: The logged-in customer. + $ref: ./StoreCustomer.yaml diff --git a/www/apps/api-reference/specs/admin/openapi.full.yaml b/www/apps/api-reference/specs/admin/openapi.full.yaml index e55657ce55..39c77898c2 100644 --- a/www/apps/api-reference/specs/admin/openapi.full.yaml +++ b/www/apps/api-reference/specs/admin/openapi.full.yaml @@ -9,6 +9,9 @@ servers: - url: http://localhost:9000 - url: https://api.medusa-commerce.com tags: + - name: Auth + description: | + Auth API routes allow you to manage an admin user's authentication. - name: Api Keys - name: Campaigns - name: Claims @@ -44168,6 +44171,196 @@ paths: $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' + /auth/session: + post: + 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' + delete: + 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' + /auth/user/{auth_provider}: + post: + 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' + /auth/user/{auth_provider}/callback: + post: + 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' + /auth/user/{auth_provider}/register: + post: + 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' components: schemas: AdminApiKeyResponse: @@ -52553,6 +52746,39 @@ components: title: revoked_at description: The api key's revoked at. format: date-time + 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' + 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. + 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' BaseApplicationMethod: type: object description: The promotion's application method. diff --git a/www/apps/api-reference/specs/admin/openapi.yaml b/www/apps/api-reference/specs/admin/openapi.yaml index 940a2d4f67..7378446b18 100644 --- a/www/apps/api-reference/specs/admin/openapi.yaml +++ b/www/apps/api-reference/specs/admin/openapi.yaml @@ -9,6 +9,9 @@ servers: - url: http://localhost:9000 - url: https://api.medusa-commerce.com tags: + - name: Auth + description: | + Auth API routes allow you to manage an admin user's authentication. - name: Api Keys - name: Campaigns - name: Claims @@ -528,6 +531,14 @@ paths: /admin/workflows-executions/{workflow_id}/{transaction_id}/{step_id}/subscribe: $ref: >- paths/admin_workflows-executions_{workflow_id}_{transaction_id}_{step_id}_subscribe.yaml + /auth/session: + $ref: paths/auth_session.yaml + /auth/user/{auth_provider}: + $ref: paths/auth_user_{auth_provider}.yaml + /auth/user/{auth_provider}/callback: + $ref: paths/auth_user_{auth_provider}_callback.yaml + /auth/user/{auth_provider}/register: + $ref: paths/auth_user_{auth_provider}_register.yaml components: securitySchemes: api_token: diff --git a/www/apps/api-reference/specs/admin/paths/auth_session.yaml b/www/apps/api-reference/specs/admin/paths/auth_session.yaml new file mode 100644 index 0000000000..a46c808ceb --- /dev/null +++ b/www/apps/api-reference/specs/admin/paths/auth_session.yaml @@ -0,0 +1,73 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_session/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthAdminSessionResponse.yaml + '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 +delete: + 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: + $ref: ../code_samples/Shell/auth_session/delete.sh + 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.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 diff --git a/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}.yaml b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}.yaml new file mode 100644 index 0000000000..2937dd005b --- /dev/null +++ b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}.yaml @@ -0,0 +1,41 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_user_{auth_provider}/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthResponse.yaml + '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 diff --git a/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_callback.yaml b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_callback.yaml new file mode 100644 index 0000000000..9d047f0a15 --- /dev/null +++ b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_callback.yaml @@ -0,0 +1,43 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_user_{auth_provider}_callback/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthResponse.yaml + '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 diff --git a/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_register.yaml b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_register.yaml new file mode 100644 index 0000000000..b580a67734 --- /dev/null +++ b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_register.yaml @@ -0,0 +1,42 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_user_{auth_provider}_register/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthResponse.yaml + '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 diff --git a/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}/post.sh b/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}/post.sh new file mode 100644 index 0000000000..79efe2b39c --- /dev/null +++ b/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}/post.sh @@ -0,0 +1 @@ +curl -X POST '{backend_url}/auth/customer/{auth_provider}' \ No newline at end of file diff --git a/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_callback/post.sh b/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_callback/post.sh new file mode 100644 index 0000000000..8974e807ef --- /dev/null +++ b/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_callback/post.sh @@ -0,0 +1 @@ +curl -X POST '{backend_url}/auth/customer/{auth_provider}/callback' \ No newline at end of file diff --git a/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_register/post.sh b/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_register/post.sh new file mode 100644 index 0000000000..ba3ff116d7 --- /dev/null +++ b/www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_register/post.sh @@ -0,0 +1 @@ +curl -X POST '{backend_url}/auth/customer/{auth_provider}/register' \ No newline at end of file diff --git a/www/apps/api-reference/specs/store/code_samples/Shell/auth_session/delete.sh b/www/apps/api-reference/specs/store/code_samples/Shell/auth_session/delete.sh new file mode 100644 index 0000000000..cca69225d8 --- /dev/null +++ b/www/apps/api-reference/specs/store/code_samples/Shell/auth_session/delete.sh @@ -0,0 +1,2 @@ +curl -X DELETE '{backend_url}/auth/session' \ +-H 'Cookie: connect.sid={sid}' \ No newline at end of file diff --git a/www/apps/api-reference/specs/store/code_samples/Shell/auth_session/post.sh b/www/apps/api-reference/specs/store/code_samples/Shell/auth_session/post.sh new file mode 100644 index 0000000000..fc9cc81528 --- /dev/null +++ b/www/apps/api-reference/specs/store/code_samples/Shell/auth_session/post.sh @@ -0,0 +1,2 @@ +curl -X POST '{backend_url}/auth/session' \ +-H 'Authorization: Bearer {jwt_token}' \ No newline at end of file diff --git a/www/apps/api-reference/specs/store/components/schemas/AdminTaxRegion.yaml b/www/apps/api-reference/specs/store/components/schemas/AdminTaxRegion.yaml index 360fa57763..a9597eba8a 100644 --- a/www/apps/api-reference/specs/store/components/schemas/AdminTaxRegion.yaml +++ b/www/apps/api-reference/specs/store/components/schemas/AdminTaxRegion.yaml @@ -87,11 +87,11 @@ properties: type: array description: The tax region's tax rates. items: - $ref: ./AdminTaxRate.yaml + type: object parent: - $ref: ./AdminTaxRegion.yaml + type: object children: type: array description: The tax region's children. items: - $ref: ./AdminTaxRegion.yaml + type: object diff --git a/www/apps/api-reference/specs/store/components/schemas/AuthAdminSessionResponse.yaml b/www/apps/api-reference/specs/store/components/schemas/AuthAdminSessionResponse.yaml new file mode 100644 index 0000000000..00217cd800 --- /dev/null +++ b/www/apps/api-reference/specs/store/components/schemas/AuthAdminSessionResponse.yaml @@ -0,0 +1,10 @@ +type: object +description: The authenticated user's details. +x-schemaName: AuthAdminSessionResponse +required: + - user +properties: + user: + title: user + description: The logged-in user. + $ref: ./AdminUser.yaml diff --git a/www/apps/api-reference/specs/store/components/schemas/AuthResponse.yaml b/www/apps/api-reference/specs/store/components/schemas/AuthResponse.yaml new file mode 100644 index 0000000000..68386983f7 --- /dev/null +++ b/www/apps/api-reference/specs/store/components/schemas/AuthResponse.yaml @@ -0,0 +1,10 @@ +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. diff --git a/www/apps/api-reference/specs/store/components/schemas/AuthStoreSessionResponse.yaml b/www/apps/api-reference/specs/store/components/schemas/AuthStoreSessionResponse.yaml new file mode 100644 index 0000000000..3ec7c5c8a0 --- /dev/null +++ b/www/apps/api-reference/specs/store/components/schemas/AuthStoreSessionResponse.yaml @@ -0,0 +1,10 @@ +type: object +description: The authenticated customer's details. +x-schemaName: AuthStoreSessionResponse +required: + - user +properties: + user: + title: user + description: The logged-in customer. + $ref: ./StoreCustomer.yaml diff --git a/www/apps/api-reference/specs/store/openapi.full.yaml b/www/apps/api-reference/specs/store/openapi.full.yaml index 1af9465814..039ef29648 100644 --- a/www/apps/api-reference/specs/store/openapi.full.yaml +++ b/www/apps/api-reference/specs/store/openapi.full.yaml @@ -9,6 +9,9 @@ servers: - url: http://localhost:9000 - url: https://api.medusa-commerce.com 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 want to purchase. @@ -63,6 +66,196 @@ tags: x-associatedSchema: $ref: '#/components/schemas/StoreShippingOption' paths: + /auth/customer/{auth_provider}: + post: + 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' + /auth/customer/{auth_provider}/callback: + post: + 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' + /auth/customer/{auth_provider}/register: + post: + 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' + /auth/session: + post: + 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' + delete: + 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' /store/carts: post: operationId: PostCarts @@ -18886,6 +19079,39 @@ components: title: revoked_at description: The api key's revoked at. format: date-time + 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' + 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. + 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' BaseApplicationMethod: type: object description: The promotion's application method. diff --git a/www/apps/api-reference/specs/store/openapi.yaml b/www/apps/api-reference/specs/store/openapi.yaml index 0a77a9714d..590530771d 100644 --- a/www/apps/api-reference/specs/store/openapi.yaml +++ b/www/apps/api-reference/specs/store/openapi.yaml @@ -9,6 +9,9 @@ servers: - url: http://localhost:9000 - url: https://api.medusa-commerce.com 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 @@ -71,6 +74,14 @@ tags: x-associatedSchema: $ref: ./components/schemas/StoreShippingOption.yaml paths: + /auth/customer/{auth_provider}: + $ref: paths/auth_customer_{auth_provider}.yaml + /auth/customer/{auth_provider}/callback: + $ref: paths/auth_customer_{auth_provider}_callback.yaml + /auth/customer/{auth_provider}/register: + $ref: paths/auth_customer_{auth_provider}_register.yaml + /auth/session: + $ref: paths/auth_session.yaml /store/carts: $ref: paths/store_carts.yaml /store/carts/{id}: diff --git 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 new file mode 100644 index 0000000000..6ffaa08c93 --- /dev/null +++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}.yaml @@ -0,0 +1,41 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_customer_{auth_provider}/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthResponse.yaml + '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 diff --git 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 new file mode 100644 index 0000000000..b737b72d35 --- /dev/null +++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_callback.yaml @@ -0,0 +1,43 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_customer_{auth_provider}_callback/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthResponse.yaml + '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 diff --git 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 new file mode 100644 index 0000000000..fe6a2e3a21 --- /dev/null +++ b/www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_register.yaml @@ -0,0 +1,42 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_customer_{auth_provider}_register/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthResponse.yaml + '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 diff --git a/www/apps/api-reference/specs/store/paths/auth_session.yaml b/www/apps/api-reference/specs/store/paths/auth_session.yaml new file mode 100644 index 0000000000..9e89642476 --- /dev/null +++ b/www/apps/api-reference/specs/store/paths/auth_session.yaml @@ -0,0 +1,73 @@ +post: + 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: + $ref: ../code_samples/Shell/auth_session/post.sh + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AuthStoreSessionResponse.yaml + '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 +delete: + 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: + $ref: ../code_samples/Shell/auth_session/delete.sh + 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.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 diff --git a/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx b/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx index 1b82797f17..56d429c588 100644 --- a/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx +++ b/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx @@ -8,7 +8,27 @@ export const metadata = { # {metadata.title} -In this document, you'll learn about how the Auth Provider is used in an authentication flow. +In this document, you'll learn how to use the Auth Provider's main service's methods to implement an authentication flow. + +## How to Register an Auth Identity + +The `register` method of the Auth Module's main service creates an auth identity that can be authenticated later. + +For example: + +```ts +const data = await authModuleService.register( + "emailpass", + // passed to auth provider + { + // ... + } +) +``` + +This method calls the `register` method of the provider specified in the first parameter and returns its data. + +--- ## How to Authenticate a User @@ -26,9 +46,7 @@ const data = await authModuleService.authenticate( This method calls the `authenticate` method of the provider specified in the first parameter and returns its data. ---- - -## Basic Authentication Flow +### Basic Authentication Flow If the `authenticate` method returns the following object: @@ -51,9 +69,7 @@ Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for ![Diagram showcasing the basic authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711373749/Medusa%20Resources/basic-auth_lgpqsj.jpg) ---- - -## Authentication with Third-Party Service Flow +### Authentication with Third-Party Service Flow If the `authenticate` method returns the following object: @@ -68,7 +84,7 @@ It means the authentication process requires the user to perform an action with ![Diagram showcasing the first part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711374847/Medusa%20Resources/third-party-auth-1_enyedy.jpg) -### validateCallback +#### validateCallback Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service. @@ -95,4 +111,4 @@ data = { } ``` -![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg) \ No newline at end of file +![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg) diff --git a/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx b/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx index 09e5bdf214..116c29fdd0 100644 --- a/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx +++ b/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx @@ -4,34 +4,79 @@ export const metadata = { # {metadata.title} -In this document, you'll learn about the `/auth` route and how to use it to create or log-in users. +In this document, you'll learn about the authentication routes and how to use them to create or log-in users. -## `/auth` Route +## Register Route -The Medusa application defines an API route at `/auth/{actor_type}/{provider}` used to obtain a token used later for authentication purposes. +The Medusa application defines an API route at `/auth/{actor_type}/{provider}/register` that creates an auth identity for an actor type, such as a `customer`. It returns a JWT token that you pass to an API route that creates the user. + +For example, if you're registering a customer, you: + +1. Send a request to `/auth/customer/emailpass/register` to retrieve the registration JWT token. +2. Send a request to the [Create Customer API route](!api!/store#customers_postcustomers) to create the customer, passing the [JWT token in the header](!api!/store#authentication). + +### Path Parameters Its path parameters are: - `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`. - `{provider}`: the auth provider to handle the authentication. For example, `emailpass`. +### Request Body Parameters + This route accepts in the request body the data that the specified authentication provider requires to handle authentication. For example, the EmailPass provider requires an `email` and `password` fields in the request body. -If the authentication is successful, you'll receive a `token` field in the response body. +### Response Fields ---- +If the authentication is successful, you'll receive a `token` field in the response body object: -## How to Use the Authentication Token - -There are two ways the returned authentication token is useful: - -1. Send authenticated requests to restricted routes. For example, if the token is of an admin user, you use it in the bearer header of subsequent requests to the admin API routes. -2. Before creating a user of an actor type, such as a `customer` or a custom actor type. You use it in the bearer header of the request to the API route that creates the user. +```json +{ + "token": "..." +} +``` [How to register Customers using the authentication route](../../../storefront-development/customers/register/page.mdx). + +--- + +## Auth Route + +The Medusa application defines an API route at `/auth/{actor_type}/{provider}` that authenticates a user of an actor type. It returns a JWT token that can be passed in [the header of subsequent requests](!api!/store#authentication) to send authenticated requests. + +For example, if you're authenticating a customer, you send a request to `/auth/customer/emailpass`. + +### Path Parameters + +Its path parameters are: + +- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`. +- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`. + +### Request Body Parameters + +This route accepts in the request body the data that the specified authentication provider requires to handle authentication. + +For example, the EmailPass provider requires an `email` and `password` fields in the request body. + +### Response Fields + +If the authentication is successful, you'll receive a `token` field in the response body object: + +```json +{ + "token": "..." +} +``` + + + +[How to login Customers using the authentication route](../../../storefront-development/customers/login/page.mdx). + + \ No newline at end of file diff --git a/www/apps/resources/app/commerce-modules/auth/create-actor-type/page.mdx b/www/apps/resources/app/commerce-modules/auth/create-actor-type/page.mdx index 371b8e1daa..5ad2ff5b50 100644 --- a/www/apps/resources/app/commerce-modules/auth/create-actor-type/page.mdx +++ b/www/apps/resources/app/commerce-modules/auth/create-actor-type/page.mdx @@ -248,7 +248,7 @@ This route is only accessible by authenticated managers. You access the manager To authenticate managers: -1. Send a `POST` request to `/auth/manager/emailpass` to create an auth identity for the manager: +1. Send a `POST` request to `/auth/manager/emailpass/register` to create an auth identity for the manager: ```bash curl -X POST 'http://localhost:9000/auth/manager/emailpass' \ diff --git a/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx b/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx index 04d0255c0b..9671682d1f 100644 --- a/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx +++ b/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx @@ -499,10 +499,10 @@ To test out the above API route: npm run dev ``` -2. Retrieve a JWT token from the `/auth/vendor/emailpass` API route: +2. Retrieve a JWT token from the `/auth/vendor/emailpass/register` API route: -```bash apiTesting testApiUrl="http://localhost:9000/auth/vendor/emailpass" testApiMethod="POST" testBodyParams={{ "email": "admin@medusa-test.com", "password": "supersecret" }} -curl -X POST 'http://localhost:9000/auth/vendor/emailpass' \ +```bash apiTesting testApiUrl="http://localhost:9000/auth/vendor/emailpass/register" testApiMethod="POST" testBodyParams={{ "email": "admin@medusa-test.com", "password": "supersecret" }} +curl -X POST 'http://localhost:9000/auth/vendor/emailpass/register' \ -H 'Content-Type: application/json' \ --data-raw '{ "email": "admin@medusa-test.com", diff --git a/www/apps/resources/app/storefront-development/customers/register/page.mdx b/www/apps/resources/app/storefront-development/customers/register/page.mdx index 290eda8101..d69d721935 100644 --- a/www/apps/resources/app/storefront-development/customers/register/page.mdx +++ b/www/apps/resources/app/storefront-development/customers/register/page.mdx @@ -9,7 +9,7 @@ export const metadata = { To register a customer, you implement the following steps: 1. Show the customer a form to enter their details. -2. Send a `POST` request to the `/auth/customer/emailpass` API route to obtain a JWT token. +2. Send a `POST` request to the `/auth/customer/emailpass/register` API route to obtain a JWT token. 3. Send a request to the [Create Customer API route](!api!/store#customers_postcustomers) pass the JWT token in the header. For example: @@ -28,7 +28,7 @@ export const fetchHighlights = [ const handleRegistration = async () => { // obtain JWT token const { token } = await fetch( - `http://localhost:9000/auth/customer/emailpass`, + `http://localhost:9000/auth/customer/emailpass/register`, { credentials: "include", method: "POST", diff --git a/www/apps/resources/generated/sidebar.mjs b/www/apps/resources/generated/sidebar.mjs index 9a48126b53..721a883442 100644 --- a/www/apps/resources/generated/sidebar.mjs +++ b/www/apps/resources/generated/sidebar.mjs @@ -205,7 +205,7 @@ export const generatedSidebar = [ "loaded": true, "isPathHref": true, "type": "link", - "path": "/commerce-modules/api-key", + "path": "/commerce-modules/auth", "title": "Overview", "children": [] }, @@ -259,18 +259,26 @@ export const generatedSidebar = [ { "loaded": true, "isPathHref": true, - "type": "link", - "path": "/commerce-modules/auth/authentication-route", - "title": "Authentication Route", - "children": [] - }, - { - "loaded": true, - "isPathHref": true, - "type": "link", - "path": "/commerce-modules/auth/auth-flows", + "type": "sub-category", "title": "Auth Flows", - "children": [] + "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "path": "/commerce-modules/auth/authentication-route", + "title": "Using API Routes", + "children": [] + }, + { + "loaded": true, + "isPathHref": true, + "type": "link", + "path": "/commerce-modules/auth/auth-flows", + "title": "Using Module's Service", + "children": [] + } + ] } ] }, diff --git a/www/apps/resources/sidebar.mjs b/www/apps/resources/sidebar.mjs index 4aa419de29..b4a576be45 100644 --- a/www/apps/resources/sidebar.mjs +++ b/www/apps/resources/sidebar.mjs @@ -94,7 +94,7 @@ export const sidebar = sidebarAttachHrefCommonOptions([ children: [ { type: "link", - path: "/commerce-modules/api-key", + path: "/commerce-modules/auth", title: "Overview", }, { @@ -129,14 +129,20 @@ export const sidebar = sidebarAttachHrefCommonOptions([ ], }, { - type: "link", - path: "/commerce-modules/auth/authentication-route", - title: "Authentication Route", - }, - { - type: "link", - path: "/commerce-modules/auth/auth-flows", + type: "sub-category", title: "Auth Flows", + children: [ + { + type: "link", + path: "/commerce-modules/auth/authentication-route", + title: "Using API Routes", + }, + { + type: "link", + path: "/commerce-modules/auth/auth-flows", + title: "Using Module's Service", + }, + ], }, ], }, diff --git a/www/utils/generated/oas-output/base/admin.oas.base.yaml b/www/utils/generated/oas-output/base/admin.oas.base.yaml index 6c793c9b54..155cdbf470 100644 --- a/www/utils/generated/oas-output/base/admin.oas.base.yaml +++ b/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 diff --git a/www/utils/generated/oas-output/base/store.oas.base.yaml b/www/utils/generated/oas-output/base/store.oas.base.yaml index eda711c043..56672ce305 100644 --- a/www/utils/generated/oas-output/base/store.oas.base.yaml +++ b/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 diff --git a/www/utils/generated/oas-output/operations/admin/delete_auth_session.ts b/www/utils/generated/oas-output/operations/admin/delete_auth_session.ts new file mode 100644 index 0000000000..628bc622a3 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider].ts b/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider].ts new file mode 100644 index 0000000000..ec41bd4bba --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_callback.ts b/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_callback.ts new file mode 100644 index 0000000000..3938e90b99 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_register.ts b/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_register.ts new file mode 100644 index 0000000000..144005a82f --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/admin/post_auth_session.ts b/www/utils/generated/oas-output/operations/admin/post_auth_session.ts new file mode 100644 index 0000000000..b7962e57d5 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/store/delete_auth_session.ts b/www/utils/generated/oas-output/operations/store/delete_auth_session.ts new file mode 100644 index 0000000000..628bc622a3 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider].ts b/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider].ts new file mode 100644 index 0000000000..a9729c7869 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_callback.ts b/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_callback.ts new file mode 100644 index 0000000000..d6e3881329 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_register.ts b/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_register.ts new file mode 100644 index 0000000000..9681b084b1 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/operations/store/post_auth_session.ts b/www/utils/generated/oas-output/operations/store/post_auth_session.ts new file mode 100644 index 0000000000..85751dabb9 --- /dev/null +++ b/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" + * +*/ + diff --git a/www/utils/generated/oas-output/schemas/AuthAdminSessionResponse.ts b/www/utils/generated/oas-output/schemas/AuthAdminSessionResponse.ts new file mode 100644 index 0000000000..b7724989e5 --- /dev/null +++ b/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" +*/ + diff --git a/www/utils/generated/oas-output/schemas/AuthResponse.ts b/www/utils/generated/oas-output/schemas/AuthResponse.ts new file mode 100644 index 0000000000..35acf29020 --- /dev/null +++ b/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. +*/ + diff --git a/www/utils/generated/oas-output/schemas/AuthStoreSessionResponse.ts b/www/utils/generated/oas-output/schemas/AuthStoreSessionResponse.ts new file mode 100644 index 0000000000..d6549e7293 --- /dev/null +++ b/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" +*/ + diff --git a/www/utils/packages/docs-generator/src/commands/clean-oas.ts b/www/utils/packages/docs-generator/src/commands/clean-oas.ts index 66803edac5..3a5486eee6 100644 --- a/www/utils/packages/docs-generator/src/commands/clean-oas.ts +++ b/www/utils/packages/docs-generator/src/commands/clean-oas.ts @@ -85,7 +85,11 @@ export default async function () { // decode oasPrefix const matchOasPrefix = OAS_PREFIX_REGEX.exec(oasPrefix) - if (!matchOasPrefix?.groups?.method || !matchOasPrefix.groups.path) { + if ( + !matchOasPrefix?.groups?.method || + !matchOasPrefix.groups.path || + matchOasPrefix.groups.path.startsWith("/auth/") + ) { return } const splitPath = matchOasPrefix.groups.path.substring(1).split("/")