Login Customer in the Storefront

In this guide, you'll learn about the two ways to login a customer in your storefront.

Next.js App Router (recommended)

Do not store the JWT in localStorage. After sdk.store.auth.login, write the token to the _aiminaabee_jwt httpOnly cookie, revalidate the customers cache tag, and transfer the guest cart.

1"use server"
2
3export async function login(
4  storeCode: string,
5  _currentState: unknown,
6  formData: FormData
7) {
8  const email = formData.get("email") as string
9  const password = formData.get("password") as string
10
11  const token = await sdk.store.auth.login(storeCode, "emailpass", {
12    email,
13    password,
14  })
15
16  if (typeof token !== "string") {
17    return "This login method requires a redirect, which is not supported."
18  }
19
20  await setAuthToken(token)
21  revalidateTag(await getCacheTag("customers"))
22  await transferCart(storeCode)
23}

setAuthToken sets _aiminaabee_jwt (httpOnly, sameSite: "strict", 7-day maxAge, secure in production). transferCart calls sdk.store.cart.transferCart with the _aiminaabee_cart_id cookie so guest line items move to the customer.

See Build a Next.js Storefront. The rest of this page covers JWT vs session and SPA examples.

Login Customer Methods

There are two ways to login a customer in your storefront:

1. Using a JWT token. This JWT token is obtained from the /auth/customer/emailpass API route and is used as a bearer token in the authorization header of all requests.
2. Using a cookie session. This method uses the /auth/session API route to set the authenticated session ID in the cookies.

The JS SDK simplifies the login approach in a single auth.login method. The upcoming sections explain the authentication approach whether you're using the JS SDK or not.

Which Authentication Method Should You Use?

The authentication method you choose depends on your use case and the type of storefront you're building.

Refer to the JS SDK Authentication guide to learn more about the differences between JWT and session authentication and which one is best for your use case.

JS SDK Authentication Configuration

Before implementing the login flow, you need to configure in the JS SDK the authentication method you're using in your storefront. This defines how the JS SDK will handle sending authenticated requests after the customer is authenticated.

For example, add the following configuration to your JS SDK initialization:

JWT

1export const sdk = new Aiminaabee({
2  // ...
3  auth: {
4    type: "jwt",
5  },
6})

Session

1export const sdk = new Aiminaabee({
2  // ...
3  auth: {
4    type: "session",
5  },
6})

The JS SDK will now pass the JWT token or the session ID cookie in the authorization header of all subsequent requests based on the authentication method you've configured.

Refer to the JS SDK Authentication guide for more information about these configurations, as well as other authentication configurations.

Authentication with JS SDK

The JS SDK provides an auth.login method that handles all authentication steps based on the configured authentication method. Then, all subsequent requests will have the necessary authentication headers or cookies.

For example, to implement the login flow in your storefront with the JS SDK:

React

1"use client" // include with Next.js 13+
2
3  import { useState } from "react"
4  import { sdk } from "@/lib/sdk"
5
6  export default function Login() {
7    const [loading, setLoading] = useState(false)
8    const [email, setEmail] = useState("")
9    const [password, setPassword] = useState("")
10
11    const handleLogin = async (
12      e: React.MouseEvent<HTMLButtonElement, MouseEvent>
13    ) => {
14      e.preventDefault()
15      if (!email || !password) {
16        return
17      }
18
19      setLoading(true)
20
21      let token: string | { location: string }
22
23      try {
24        token = await sdk.store.auth.login("us", "emailpass", {
25          email,
26          password,
27        })
28      } catch (error) {
29        alert(`An error occurred while logging in: ${error}`)
30        return
31      }
32
33      if (typeof token !== "string") {
34        alert("Authentication requires more actions, which isn't supported by this flow.")
35        return
36      }
37
38      // all next requests will be authenticated
39      const { customer } = await sdk.store.customer.retrieve("us")
40
41      console.log(customer)
42      setLoading(false)
43    }
44
45    return (
46      <form>
47        <input
48          type="email"
49          name="email"
50          value={email}
51          placeholder="Email"
52          onChange={(e) => setEmail(e.target.value)}
53        />
54        <input
55          type="password"
56          name="password"
57          value={password}
58          placeholder="Password"
59          onChange={(e) => setPassword(e.target.value)}
60        />
61        <button
62          disabled={loading}
63          onClick={handleLogin}
64        >
65          Login
66        </button>
67      </form>
68    )
69  }

JS SDK

1const handleLogin = async () => {
2    let token: string | { location: string }
3
4    try {
5      token = await sdk.store.auth.login("us", "emailpass", {
6        email,
7        password,
8      })
9    } catch (error) {
10      alert(`An error occurred while logging in: ${error}`)
11      return
12    }
13
14    if (typeof token !== "string") {
15      alert("Authentication requires more actions, which isn't supported by this flow.")
16      return
17    }
18
19    // all next requests will be authenticated
20    const { customer } = await sdk.store.customer.retrieve("us")
21
22    console.log(customer)
23  }

In the example above, you:

1. Create a handleLogin function that logs in a customer.
2. In the function, you log in the customer using the sdk.auth.login method.
   • If an error occurs, show an alert and exit execution.
   • The method may return an object with a location property. This occurs when using third-party authentication providers. Learn more about implementing third-party authentication in the Third-Party Login guide.
   • Otherwise, the authentication was successful.
3. All subsequent requests are now authenticated. As an example, you send a request to obtain the logged-in customer's details.

Authentication without JS SDK

If you're not using the JS SDK, the next sections cover the general flow for authenticating a customer in your storefront for both methods.

1. Using a JWT Token

The first authentication approach is to pass an authenticated JWT token in the authorization header of all requests. You can do that by:

1. Retrieving a JWT token from the /auth/customer/emailpass Authenticate Customer API route:

1curl -X POST '{backend_url}/auth/customer/emailpass' \
2-H 'Content-Type: application/json' \
3--data-raw '{
4  "email": "customer@gmail.com",
5  "password": "supersecret"
6}'

2. Passing the token in the authorization header of all subsequent requests, as explained in the API reference:

1Authorization: Bearer {jwt_token}

Store the JWT based on your platform. On Next.js, use the _aiminaabee_jwt httpOnly cookie. SPAs may use memory or sessionStorage. Avoid localStorage for tokens when you can.

2. Using a Cookie Session

The second authentication approach is to authenticate the customer with a cookie session. You do that by:

1. Retrieving a JWT token from the /auth/customer/emailpass Authenticate Customer API route:

1curl -X POST '{backend_url}/auth/customer/emailpass' \
2-H 'Content-Type: application/json' \
3--data-raw '{
4  "email": "customer@gmail.com",
5  "password": "supersecret"
6}'

2. Sending a request to the /auth/session Authentication Session API route passing in the authorization header the token as a Bearer token. This sets the authenticated session ID in the cookies:

1curl -X POST '{backend_url}/auth/session' \
2-H 'Authorization: Bearer {jwt_token}'

3. Passing the cookie session ID in all subsequent requests:

cURL

1curl '{backend_url}/store/products' \
2-H 'Cookie: connect.sid={sid}'

Fetch

1fetch(`<BACKEND_URL>/store/products`, {
2  credentials: "include",
3})