Authentication

The GraphQL API authorizes requests with a bearer token sent via the HTTP Authorization header:

POST https://{bigcommerce_storefront_domain}.com/graphql
  Accept: application/json
  Content-Type: application/json
  Authorization: Bearer {token}

We’ll cover the methods for creating this token, as well as how to utilize the auto-generated token that is available in Stencil and Script Manager code.

Correlating Requests

In addition to the bearer token for authentication, it may be wise in some cases to provide an X-Correlation-Id header.

When multiple GraphQL requests are critical to a single operation within your application, providing the same value for this header is used to indicate that relationship to BigCommerce, where it might be used for request routing. The X-Correlation-Id value should be in UUID format.

POST https://{bigcommerce_storefront_domain}.com/graphql
  Accept: application/json
  Content-Type: application/json
  Authorization: Bearer {token}
  X-Correlation-Id: 074c7d82-235c-4dfd-b32a-65269dfcd36b

Creating a Standard Token

You can create a token for use by any storefront on any domain, as long as you indicate the appropriate allowed origin(s) in the token request.

In general, this type of GraphQL Storefront API token is not considered sensitive, and it is safe to expose in web browsers, for example, in HTML documents. In a client-side context, this token can only expose information that an individual shopper is already privy to when browsing a storefront or allow them to perform actions that shoppers can perform (e.g., creating a shopper cart).

When used in a client-side context, standard tokens maintain user context (such as for customer-specific pricing or cart/checkout management) via a BigCommerce-provided session cookie. When used in a server-side context, customer context is provided by a Customer Access Token (see below).

It is possible to create a long-lived token that does not expire, which is appropriate if you wish to create a token once and store it in an application environment. In the interest of better security, it is recommended to create shorter-lived tokens and rotate them periodically by calling this API to generate a new one before the old one expires.

Standard tokens can be created using the Storefront API Token endpoint:

POST https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/api-token

{
  "channel_id": 1,            // int (must be a valid channel ID on the store)
  "expires_at": 1602288000,   // integer unix timestamp in seconds (required)
  "allowed_cors_origins": [   // array (accepts 2 origins currently)
    "https://example.com"
  ]
}

Creating a Private Token

Private tokens are designed for headless server-to-server integrations. They do not require a session and are the recommended token type for new headless server-to-server applications.

Private token access scopes

Only private tokens use access scopes; storefront and customer access tokens do not. Scopes restrict which GraphQL fields the token can access. The token must include all scopes required by every field in the selection (including nested fields).

Scopes are independent: There is no hierarchy or inheritance. For example, Customer does not include or imply Unauthenticated—they cover different areas. You need more than one scope only when your query selects fields that require different scopes (e.g. checkout { order { id } } requires both Unauthenticated for checkout and Customer for order).

Scope identifiers (use these in the create request):

Scopes are required when creating a private token. The API rejects requests with no scopes. Apply the principle of least privilege—request only the scopes you need.

When the token lacks a scope required by a field, the API returns a GraphQL response with errors. Affected fields may be null in data. The error includes extensions.code: "INSUFFICIENT_ACCESS_SCOPE" and extensions.requiredScopes (the scope identifiers required by that field):

{
  "data": null,
  "errors": [
    {
      "message": "The provided token does not include the scopes required to resolve this field.",
      "path": ["company"],
      "extensions": {
        "code": "INSUFFICIENT_ACCESS_SCOPE",
        "requiredScopes": ["B2B"]
      }
    }
  ]
}

You must specify scopes when creating a private token. Private tokens can be created using the Private Storefront API Token endpoint:

POST https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/api-token-private

{
  "channel_id": 1,            // int (must be a valid channel ID on the store)
  "expires_at": 1602288000,   // integer unix timestamp in seconds (required)
  "scopes": [                 // access scope identifiers (required)
    "Unauthenticated",
    "Customer",
    "B2B"
  ]
}

Authenticating with an Auto-Generated Stencil Token

Stencil code has access to an automatically created GraphQL Storefront token that is used for queries in YAML Front Matter and can also be passed along for use in client-side code.

Client code in BigCommerce Stencil themes or Script Manager can be passed a token at render time with the {{settings.storefront_api.token}} Handlebars object.

Customer Access Tokens

The customer access token is a unique identifier that is associated with a specific customer’s account. This token is used in combination with a Private Token, provided in a special header, to provide an individual customer context for a request.

You can only obtain and use a customer access token for server-to-server requests.

There are two ways to create a customer access token:

1. The login mutation - This supports a typical login scenario, explicitly requiring a customer’s login credentials in order to obtain the customer access token for their account.

Headers

POST https://{{storeDomain}}/graphql
Authorization: Bearer {Storefront token}
Accept: application/json
Content-Type: application/json

Login Mutation Body

mutation Login($email: String!, $pass: String!) {
 login(email: $email, password: $pass) {
   result
   customer {
     entityId
     email
   }
   customerAccessToken {
     value
     expiresAt
   }
 }
}

If successful, the login mutation above will return the customer’s ID, email address, and a customer access token that is specifically for their account.

2. The loginWithCustomerLoginJwt mutation - This supports a single sign-on workflow in which a trusted application authenticates a customer without requiring their credentials. This utilizes the steps described for the Customer Login API to create a JWT.

Headers

POST https://{{storeDomain}}/graphql
Authorization: Bearer {Storefront token}
Accept: application/json
Content-Type: application/json

loginWithCustomerLoginJwt Mutation Body

mutation Login($jwt: String!) {
 loginWithCustomerLoginJwt(jwt: $jwt) {
   customer {
     entityId
     email
   }
   customerAccessToken {
     value
     expiresAt
   }
 }
}

Similar to the regular login mutation, the loginWithCustomerLoginJwt mutation will return the customer’s ID, email address, and a customer access token associated with their specific account.

However a customer access token was obtained, this token is passed in the X-Bc-Customer-Access-Token header with any GraphQL request to provide the customer context. When this header is provided, requests and the data they mutate or return are tailored to the customer, whether that involves returning differentiated pricing for products, determining the ownership of a new cart, or querying the customer’s address or order information.

Example Request Headers

POST https://{{storeDomain}}/graphql
Authorization: Bearer {Storefront token or Private Token}
Accept: application/json
Content-Type: application/json
X-Bc-Customer-Access-Token: {Customer access token}

Customer Impersonation Tokens

Customer impersonation tokens (CIT) are an alternative to standard tokens, also used as the Bearer token to authenticate GraphQL requests. A CIT has the ability to “impersonate” any customer context just by providing a customer’s ID in a special header.

Customer impersonation tokens can only be used in server-side requests. Because of their elevated privileges, they should be considered a sensitive credential similar to an OAuth token for BigCommerce’s administrative APIs and never exposed to end users. Requests from browsers using a customer impersonation token will be rejected.

You can generate customer impersonation token using the following endpoint:

POST https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/api-token-customer-impersonation
{
  "channel_id": 1,
  "expires_at": 1602288000
}

Unlike standard tokens, customer impersonation tokens do not require allowed origins to be designated, since they are never used in a client-side context.

Customer Impersonation Token authenticated requests made to the GraphQL API receive store information from the perspective of the customer corresponding to the customer ID specified in the X-Bc-Customer-Id header sent with the GraphQL POST request.

CITs are not customer-specific; they and are generally long-lived and stored as static configuration in the applications that use them.

Example Request Headers

POST https://{{storeDomain}}/graphql
Authorization: Bearer {Storefront token}
Accept: application/json
Content-Type: application/json
X-Bc-Customer-Id: 123

Revoke A Token

If a token is compromised and you wish to invalidate the Storefront API connection for your token, you can make a DELETE request to the /api-token endpoint. Use this in emergencies, and do not revoke tokens unnecessarily. Instead, it is best practice to use a shorter expiration and allow them to expire naturally.

Use the following endpoint to revoke a token in the case of an emergency:

DELETE  https://api.bigcommerce.com/stores/[store_hash]/v3/storefront/api-token

Customer Logout Mutation

You can use the following logout mutation to sign out of a customer account:

mutation Logout {
  logout {
    result
  }
}

This will clear the session cookie in a client-side context, which has the effect of logging out the shopper, and will also destroy the session on the BigCommerce back-end for both client-side and server-side contexts.

Resources

• GraphQL Storefront API - Authentication