> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/chord-oms/shopify/developer-tools/gatsby/guides/user-authentication.md).
# User Authentication
The Chord Performance Gatsby theme and starter support [Shopify customer accounts](https://help.shopify.com/en/manual/customers/customer-accounts). A customer can log into their Shopify store customer account on a Chord Performance Gatsby site and see their order history and saved addresses.
If the Shopify store is on Shopify Plus, the Shopify Plus Multipass feature can transfer the authenticated user session from the Gatsby site to Shopify checkout. In other words, if a user logs into their Shopify customer account via the Gatsby site, and then clicks "Check Out" and is brought to Shopify checkout, they will continue to be logged in and have access to their saved addresses. **This transfer of user session from the Gatsby site to Shopify checkout is *****only***** possible for Shopify Plus stores with Multipass enabled.** Gatsby sites for non-Shopify Plus stores can still support Shopify customer accounts, but the user session will not be transferred to Shopify checkout.
## Configure Shopify
### Enable customer accounts
Customer accounts must be enabled in the Shopify store admin to use this feature. See [Shopify's docs](https://help.shopify.com/en/manual/checkout-settings/customer-accounts) for step-by-step instructions for enabling customer accounts.
### Enable Multipass
If the Shopify Store is a Shopify Plus store, Multipass can be enabled to allow user sessions to be transferred from the Gatsby site to Shopify checkout. See [Shopify's docs](https://shopify.dev/docs/admin-api/rest/reference/plus/multipass) for step-by-step instructions for enabling Multipass.
### Update email template
Shopify's `Customer account password reset` transactional email template contains a link to the Shopify storefront. Since the Gatsby site has a different URL, the link in the email template needs to be updated to point to the Gatsby site.
Navigate to **Settings -> Notifications -> Customer account password reset** in the Shopify store admin. You'll see this block of code in the email template:
{% code title="Password reset email template" %}
```html
Reset your password
```
{% endcode %}
Replace it with this block of code, inserting your Gatsby site's domain name in place of ``:
{% code title="Password reset email template" %}
```html
{% raw %}
{% assign url_parts = customer.reset_password_url | split: '/' %}
{% endraw %}
Reset your password
```
{% endcode %}
## Configure Gatsby Site
`@chordcommerce/gatsby-starter-performance` added account registration, login, and profile React components in `v2.1.0`. Make sure to use a compatible version.
### Development
No specific changes need to be made to the development environment to support Shopify customer accounts without Multipass.
### Multipass API endpoint
In order to support the Multipass flow, the Gatsby site needs to expose a single API endpoint that creates a Multipass token. Creating a Multipass token requires a Multipass secret key, so this cannot be done client-side for security reasons. This API endpoint can be hosted anywhere.
To make local development easier, the [gatsby-starter-performance](https://github.com/chordcommerce/gatsby-starter-performance) repo includes a simple Node.js script that starts a local web server and has all the code necessary for creating the token. To start the server locally, run:
{% code title="yarn" %}
```shell
$ yarn start:multipass
```
{% endcode %}
This simply starts a local web server at by running the Node.js script at [scripts/shopify-multipass.js](https://github.com/chordcommerce/gatsby-starter-performance/blob/main/scripts/shopify-multipass.js).
### Multipass environment configuration
Two environment variables need to be added to the Gatsby site's `.env` file:
`GATSBY_SHOPIFY_MULTIPASS_URL`: This variable tells `gatsby-theme-shopify` where to find the Multipass token creation endpoint. In development, its value is probably `http://localhost:3000` as described above in the "Multipass API endpoint" section.
`SHOPIFY_MULTIPASS_SECRET`: This variable is used by the Node.js script at [scripts/shopify-multipass.js](https://github.com/chordcommerce/gatsby-starter-performance/blob/main/scripts/shopify-multipass.js). Its value is the Multipass secret that can be [found in the Shopify admin](https://shopify.dev/docs/admin-api/rest/reference/plus/multipass). Make sure to keep this secret private. It should not be exposed client-side.
### Production
No specific changes need to be made to a production site to support Shopify customer accounts without Multipass.
### Multipass API endpoint
As covered above, a Gatsby site needs to expose a single API endpoint that creates a Multipass token. In production, you may choose to run this API endpoint anywhere. If you're hosting your site in Netlify, the [gatsby-starter-performance](https://github.com/chordcommerce/gatsby-starter-performance) repo includes a Netlify function to supply this functionality. The code for the function can easily be adapted to work in other infrastructure.
### Multipass environment configuration
Two environment variables need to be added to the Gatsby site's `.env` file:
`GATSBY_SHOPIFY_MULTIPASS_URL`: This variable tells `gatsby-theme-performance` where to find the Multipass token creation endpoint.
{% hint style="info" %}
If using Netlify functions, the endpoint will be available via a [predictable URL](https://docs.netlify.com/functions/build-with-javascript/):
`GATSBY_SHOPIFY_MULTIPASS_URL=/.netlify/functions/shopify-multipass`
{% endhint %}
`SHOPIFY_MULTIPASS_SECRET`: This variable is used by the Node.js script at [scripts/shopify-multipass.js](https://github.com/chordcommerce/gatsby-starter-performance/blob/main/scripts/shopify-multipass.js). Its value is the Multipass secret that can be [found in the Shopify admin](https://shopify.dev/docs/admin-api/rest/reference/plus/multipass). Make sure to keep this secret private. It should not be exposed client-side.
## Checklist
Here's a summary of the changes you'll need to make to fully support Shopify customer authentication on your Gatsby site:
* [ ] **Shopify store admin:**
* [ ] Enable customer accounts
* [ ] Enable Multipass
* [ ] Update email template
* [ ] **Gatsby site:**
* [ ] Add Multipass API endpoint
* [ ] Add Multipass environment variables `GATSBY_SHOPIFY_MULTIPASS_URL` and `SHOPIFY_MULTIPASS_SECRET` to `.env`
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.chord.co/chord-oms/shopify/developer-tools/gatsby/guides/user-authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.