asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: updates following authentication flow changes (#8706)

Browse Source 
* 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
This commit is contained in:
Shahed Nasser
2024-08-27 15:47:39 +03:00
committed by GitHub
parent 9197bdd77b
commit 0c4f4c8a11
55 changed files with 1553 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/cli/oas/medusa-oas-cli/redocly/redocly-config.yaml
+7 -10
View File
@@ -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
www/apps/api-reference/app/_mdx/admin.mdx
+3 -3
View File
@@ -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:
www/apps/api-reference/app/_mdx/store.mdx
+2 -10
View File
@@ -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' \
}'
```
<Note>
{/* TODO add link to implementing login with google guide. */}
Alternatively, you can use the `google` provider instead of `emailpass`.
</Note>
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:
www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/delete.sh
+2
View File
@@ -0,0 +1,2 @@
curl -X DELETE '{backend_url}/auth/session' \
-H 'Cookie: connect.sid={sid}'
www/apps/api-reference/specs/admin/code_samples/Shell/auth_session/post.sh
+2
View File
@@ -0,0 +1,2 @@
curl -X POST '{backend_url}/auth/session' \
-H 'Authorization: Bearer {jwt_token}'
www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}/post.sh
+1
View File
@@ -0,0 +1 @@
curl -X POST '{backend_url}/auth/user/{auth_provider}'
www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_callback/post.sh
+1
View File
@@ -0,0 +1 @@
curl -X POST '{backend_url}/auth/user/{auth_provider}/callback'
www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_register/post.sh
+1
View File
@@ -0,0 +1 @@
curl -X POST '{backend_url}/auth/user/{auth_provider}/register'
www/apps/api-reference/specs/admin/components/schemas/AuthAdminSessionResponse.yaml
+10
View File
@@ -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
www/apps/api-reference/specs/admin/components/schemas/AuthResponse.yaml
+10
View File
@@ -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.
www/apps/api-reference/specs/admin/components/schemas/AuthStoreSessionResponse.yaml
+10
View File
@@ -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
www/apps/api-reference/specs/admin/openapi.full.yaml
+226
View File
@@ -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.
www/apps/api-reference/specs/admin/openapi.yaml
+11
View File
@@ -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:
www/apps/api-reference/specs/admin/paths/auth_session.yaml
+73
View File
@@ -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
www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}.yaml
+41
View File
@@ -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
www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_callback.yaml
+43
View File
@@ -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
www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_register.yaml
+42
View File
@@ -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
www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}/post.sh
+1
View File
@@ -0,0 +1 @@
curl -X POST '{backend_url}/auth/customer/{auth_provider}'
www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_callback/post.sh
+1
View File
@@ -0,0 +1 @@
curl -X POST '{backend_url}/auth/customer/{auth_provider}/callback'
www/apps/api-reference/specs/store/code_samples/Shell/auth_customer_{auth_provider}_register/post.sh
+1
View File
@@ -0,0 +1 @@
curl -X POST '{backend_url}/auth/customer/{auth_provider}/register'
www/apps/api-reference/specs/store/code_samples/Shell/auth_session/delete.sh
+2
View File
@@ -0,0 +1,2 @@
curl -X DELETE '{backend_url}/auth/session' \
-H 'Cookie: connect.sid={sid}'
www/apps/api-reference/specs/store/code_samples/Shell/auth_session/post.sh
+2
View File
@@ -0,0 +1,2 @@
curl -X POST '{backend_url}/auth/session' \
-H 'Authorization: Bearer {jwt_token}'
www/apps/api-reference/specs/store/components/schemas/AdminTaxRegion.yaml
+3 -3
View File
@@ -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
www/apps/api-reference/specs/store/components/schemas/AuthAdminSessionResponse.yaml
+10
View File
@@ -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
www/apps/api-reference/specs/store/components/schemas/AuthResponse.yaml
+10
View File
@@ -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.
www/apps/api-reference/specs/store/components/schemas/AuthStoreSessionResponse.yaml
+10
View File
@@ -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
www/apps/api-reference/specs/store/openapi.full.yaml
+226
View File
@@ -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.
www/apps/api-reference/specs/store/openapi.yaml
+11
View File
@@ -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}:
www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}.yaml
+41
View File
@@ -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
www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_callback.yaml
+43
View File
@@ -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
www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_register.yaml
+42
View File
@@ -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
www/apps/api-reference/specs/store/paths/auth_session.yaml
+73
View File
@@ -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
www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
+25 -9
View File
@@ -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)
![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)
www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx
+56 -11
View File
@@ -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": "..."
}
```
<Note title="Example">
[How to register Customers using the authentication route](../../../storefront-development/customers/register/page.mdx).
</Note>
---
## 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": "..."
}
```
<Note title="Example">
[How to login Customers using the authentication route](../../../storefront-development/customers/login/page.mdx).
</Note>
www/apps/resources/app/commerce-modules/auth/create-actor-type/page.mdx
+1 -1
View File
@@ -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' \
www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx
Vendored
+3 -3
View File
@@ -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",
www/apps/resources/app/storefront-development/customers/register/page.mdx
+2 -2
View File
@@ -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",
www/apps/resources/generated/sidebar.mjs
+20 -12
View File
@@ -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": []
}
]
}
]
},
www/apps/resources/sidebar.mjs
+14 -8
View File
@@ -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",
},
],
},
],
},
www/utils/generated/oas-output/base/admin.oas.base.yaml
+3
View File
@@ -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
+3
View File
@@ -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
+44
View File
@@ -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
+42
View File
@@ -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
+43
View File
@@ -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
+43
View File
@@ -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
+37
View File
@@ -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
+44
View File
@@ -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
+42
View File
@@ -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
+43
View File
@@ -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
+43
View File
@@ -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
+37
View File
@@ -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
+14
View File
@@ -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
+14
View File
@@ -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
+14
View File
@@ -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"
*/
www/utils/packages/docs-generator/src/commands/clean-oas.ts
+5 -1
View File
@@ -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("/")