diff --git a/www/apps/docs/content/upgrade-guides/medusa-core/1-17-0.md b/www/apps/docs/content/upgrade-guides/medusa-core/1-17-0.md
new file mode 100644
index 0000000000..34c64f2de6
--- /dev/null
+++ b/www/apps/docs/content/upgrade-guides/medusa-core/1-17-0.md
@@ -0,0 +1,55 @@
+---
+description: "Actions Required for v.1.17.0"
+sidebar_custom_props:
+  iconName: "server-stack-solid"
+---
+
+# v1.17.0
+
+Version 1.17.0 of Medusa ships new and improved authentication methods.
+
+## Overview
+
+### Breaking changes
+
+This release comes with changes to our authentication methods, which has led to a breaking change in the client-side usage of our API token method.
+
+The header used for API token authentication has changed from a Bearer authorization scheme to a custom header specific to Medusa, `x-medusa-access-token`.
+
+Specifically, an authenticated request with API tokens have changed from:
+
+```bash
+# PREVIOUSLY
+curl -L GET '<BACKEND_URL>/admin/products' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {api_token}'
+```
+
+To:
+
+```bash
+# NOW
+curl -L GET '<BACKEND_URL>/admin/products' \
+-H 'Content-Type: application/json' \
+-H 'x-medusa-access-token: {api_token}'
+```
+
+Additionally, the underlying strategies of session authentication have been updated in both the Store and Admin API, causing existing alive sessions to no longer be valid.
+
+:::note
+
+Existing sessions will not be converted to fit the updated strategies. Make sure to plan your upgrade accordingly.
+
+:::
+
+---
+
+## How to Update
+
+Run the following command in your project:
+
+```bash npm2yarn
+npm install @medusajs/medusa@1.17.0
+```
+
+To avoid unexpected issues with dependencies, it is also recommended to update all other Medusa plugins or packages you have installed.