asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 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
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