Customer context in the GraphQL Storefront API

Many GraphQL Storefront API requests can carry a customer context: the identity of a signed-in shopper. Customer context is separate from the bearer token you use to authenticate the request. A storefront token, private token, or customer impersonation token authorizes your application to call the API at all; customer context tells the API which shopper the request represents.

Customer context affects requests in two distinct ways:

• It can change the response. Many queries return data regardless of whether a customer is signed in, but return different data when one is. For example, you can query product data with no customer context, but a signed-in customer who belongs to a price list receives their customer-specific pricing in the same query. The operation works either way; the customer context only changes what comes back.
• It can be required for the operation to work at all. Some queries and mutations do nothing, return empty data, or error without a customer context. Many of these are self-evident, such as reading the customer object or running addCustomerAddress. Others are not: the registerCompany mutation, for instance, must be called as a signed-in customer.

If an operation returns empty data or an authentication error when you expected results, confirm that you’re sending a customer context. The Operations that require customer context table lists the known cases.

How customer context is established

You establish customer context differently depending on where your code runs and what kind of authentication token you’re using.

Client-side: the session cookie

On a Stencil storefront, customer context travels in a session cookie. The cookie is set automatically when a customer signs in through the login mutation, and the browser sends it with subsequent GraphQL requests. This is the same session cookie the storefront already tracks for the shopper, so a customer who is signed in to the storefront is automatically in context for client-side GraphQL requests. You don’t manage the cookie yourself; the browser and the storefront handle it.

Server-side: the customer access token

For server-to-server requests there is no browser session cookie, so you supply customer context explicitly with the X-Bc-Customer-Access-Token header. You obtain the token value with a login mutation and send it alongside your private token. The rest of this page covers how to obtain and use a customer access token.

Server-side: a customer ID header

A customer impersonation token allows you to provide customer context a third way: you send the target customer’s ID in the X-Bc-Customer-Id header, and the token authorizes the request to act as that customer without a customer login. Because a single customer impersonation token can assume the context of any customer, it is a highly sensitive credential and must stay server-side. For how to create and use one, see Customer impersonation tokens on the Authentication page.

Operations that require customer context

The following operations only return meaningful data, or only work at all, when the request carries a customer context.

By contrast, operations that create or recover an account do not require an existing customer context, because you use them precisely when no customer is signed in yet: registerCustomer, login, loginWithCustomerLoginJwt, requestResetPassword, and resetPassword.

Customer access tokens

A customer access token is unique to an individual user’s account because it represents an authenticated storefront session for GraphQL requests. You can obtain and use a customer access token only for server-to-server requests. Therefore, you must use the customer access token alongside a private token. A customer access token becomes invalid on all devices when you log out of a single device.

Obtaining a customer access token

There are two options to obtain a customer access token.

1. Login mutation
2. Login with a JWT

Login mutation

Enter your user email and password to use the login mutation. When using the login mutation in a server-to-server context, the mutation will return a customer access token in response to login actions as part of the GraphQL body instead of a cookie header. From there, you can store the customer access token in the presentation layer’s session management system and send it with future GraphQL requests. If the login mutation request is from a browser, we will not return the customer access token in the body, and will instead set a cookie.

# Creates a customer access token
POST https://{{storeDomain}}/graphql
Authorization: Bearer {Private token}
accept: application/json
content-type: application/json
mutation Login($email: String!, $pass: String!) {
 login(email: $email, password: $pass) {
   result
   customer {
     entityId
     email
   }
   customerAccessToken {
     value
     expiresAt
   }
 }
}

{
    "email": "user@email.com",
    "pass": "password"
}

Login with a JWT

There are two options for logging in using a JWT.

1. Customer Login API

The Customer Login API enables third-party services to securely authenticate a logged-in customer by accepting a signed JWT from BigCommerce. This allows the third party to verify the customer’s identity before granting access to sensitive information. For more details, see the Customer Login API article.

2. loginWithCustomerLoginJwt

The loginWithCustomerLoginJwt mutation allows you to pass a customer JSON web token instead of the user’s email and password. A 3rd party signs the JSON web token used. In this scenario, you will generate a JWT that contains key information in the payload for the login to be successful. You will use this JWT in the login mutation to receive a customer access token. For instructions on creating a JWT, see the Customer Login API article for instructions.

# Creates a customer access token
POST https://{{storeDomain}}/graphql
Authorization: Bearer {Private token}
accept: application/json
content-type: application/json
mutation Login($jwt: String!) {
 loginWithCustomerLoginJwt(jwt: $jwt) {
   customer {
     entityId
     email
   }
   customerAccessToken {
     value
     expiresAt
   }
 }
}

{"jwt": "your_jwt_token"}

Using a customer access token

You can assign the customer access token obtained using one of the mutations described above to the X-Bc-Customer-Access-Token header for future queries. You can use this token for a specific shopper session access until it is invalidated or if it expires due to time. The token is invalidated when you use the logout mutation with the X-Bc-Customer-Access-Token header.

POST https://{{storeDomain}}/graphql
Authorization: Bearer {Private token}
X-Bc-Customer-Access-Token: {Customer access token}
accept: application/json
content-type: application/json
query CustomerAttributes {
  customer {
    firstName
    lastName
    email
    entityId
    customerGroupId
    attributeCount
    attributes {
      shirtSize: attribute(entityId:123) {
        entityId
        value
      }
      favoriteColor: attribute(entityId:456) {
        entityId
        value
      }
    }
  }
}

Further reading

• Authenticating requests to the GraphQL Storefront API
• Signing customers in
• Customer impersonation tokens
• GraphQL API reference