From a3fe2b536f591fee0d1de219249076b01a0924a8 Mon Sep 17 00:00:00 2001 From: David Preininger <61542192+dPreininger@users.noreply.github.com> Date: Fri, 29 Sep 2023 23:54:05 +0200 Subject: [PATCH] docs(medusa): Authentication overhaul (#5156) * implemented bearer auth * changed naming strat * changed session auth to not use jwt * typo * changed auth header prefix for admin api token auth * fixed supporting functions to work with new session type * removed database calls for bearer auth improving performance * removed unused deps * changed auth in tests * added integration tests * Accepted suggested change Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com> * Typo Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * more typos Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * proper formatting Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * removed endregion Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * removed startregion Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * fixed admin JWT integration test * added more fixes to integration tests * Update OAS * Create fluffy-donkeys-hope.md * created API reference for new auth * implemented getToken in medusa-js * Apply suggestions from code review Co-authored-by: Shahed Nasser * Apply suggestions from code review Co-authored-by: Shahed Nasser * deleted files which should be autogenerated * Update fluffy-donkeys-hope.md * JSDoc update Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com> * added missing route exports * implemented runtime domain safety in jwt token manager * fixed jwt manager * lint get-token files * Update fluffy-donkeys-hope.md * Revert "deleted files which should be autogenerated" This reverts commit cd5e86623b822e6a6ac37322b952143ccc493df9. * Revert "Apply suggestions from code review" This reverts commit f02f07ce58fd9fcc2dfc80cadbb9df2665108d65. * Revert "created API reference for new auth" This reverts commit c9eafbb36453f5cf8047c79e94f470cb2d023c7d. * added api reference * renamed header for sending api access tokens * updated api token header in docs * medusa-js - changed apiKey header --------- Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com> Co-authored-by: olivermrbl Co-authored-by: Shahed Nasser --- www/apps/api-reference/app/_mdx/admin.mdx | 38 ++++++++++++++++++++--- www/apps/api-reference/app/_mdx/store.mdx | 33 ++++++++++++++++++-- 2 files changed, 64 insertions(+), 7 deletions(-) diff --git a/www/apps/api-reference/app/_mdx/admin.mdx b/www/apps/api-reference/app/_mdx/admin.mdx index e6c9e88d51..a4d905f4a2 100644 --- a/www/apps/api-reference/app/_mdx/admin.mdx +++ b/www/apps/api-reference/app/_mdx/admin.mdx @@ -32,7 +32,7 @@ Aside from this API reference, check out the [Commerce Modules](https://docs.med ## Authentication -There are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID. +There are three ways to send authenticated requests to the Medusa server: Using a user's API token, using a JWT token or using a Cookie Session ID. ### API Token @@ -103,12 +103,10 @@ export default UpdateUser`, #### How to Use the API Token -The API token can be used for Bearer Authentication. It's passed in the -`Authorization` header as the following: - +The API token can be used by providing it in `x-medusa-access-token` header: ```bash -Authorization: Bearer {api_token} +x-medusa-access-token: {api_token} ``` You can also pass it to client libraries: @@ -154,6 +152,36 @@ You can also pass it to client libraries: pathName="/api/admin" /> +### JWT Token + +Use a JWT token to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications. + +#### How to Obtain the JWT Token + +JWT tokens are obtained by sending a request to the [User Login (JWT) endpoint](#auth_posttoken) passing it the user's email and password in the request body. For example: + +```bash +curl -X POST 'https://medusa-url.com/admin/auth/token' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "email": "user@example.com", + "password": "supersecret" +}' + +``` + +If authenticated successfully, an object is returned in the response with the property `access_token` being the JWT token. + +#### How to Use the JWT Token + +The JWT token can be used for Bearer Authentication. It's passed in the +`Authorization` header as the following: + + +```bash +Authorization: Bearer {jwt_token} +``` + ### Cookie Session ID Use a cookie session to send authenticated requests. diff --git a/www/apps/api-reference/app/_mdx/store.mdx b/www/apps/api-reference/app/_mdx/store.mdx index d267363aa8..3b1d20d172 100644 --- a/www/apps/api-reference/app/_mdx/store.mdx +++ b/www/apps/api-reference/app/_mdx/store.mdx @@ -33,8 +33,37 @@ Aside from this API reference, check out the [Commerce Modules](https://docs.med ## Authentication -To send requests as an authenticated customer, you must use the Cookie -Session ID. +There are two ways to send authenticated requests to the Medusa server: Using a JWT token or using a Cookie Session ID. + +### JWT Token + +Use a JWT token to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications. + +#### How to Obtain the JWT Token + +JWT tokens are obtained by sending a request to the [Customer Login (JWT) endpoint](#auth_authtoken) passing it the customer's email and password in the request body. For example: + +```bash +curl -X POST 'https://medusa-url.com/store/auth/token' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "email": "user@example.com", + "password": "supersecret" +}' + +``` + +If authenticated successfully, an object is returned in the response with the property `access_token` being the JWT token. + +#### How to Use the JWT Token + +The JWT token can be used for Bearer Authentication. It's passed in the +`Authorization` header as the following: + + +```bash +Authorization: Bearer {jwt_token} +``` ### Cookie Session ID