Authentication

Introduction

As we’ve learned, two different GraphQL APIs support B2B operations. The BigCommerce GraphQL Storefront API and B2B GraphQL API each have their own approach to authentication and customer context. Here we’ll explore two different authentication flows, the choice of which depends on which API you are starting with.

Terms to be familiar with:

• Storefront Token or BigCommerce Storefront Token: A bearer token generated with the REST Admin API that must be included with any request to the BigCommerce GraphQL Storefront API. These are either client-side tokens or private tokens (for server-side). These tokens are not customer-specific; customer context is handled via a separate mechanism.
• B2B Storefront Token: A bearer token included with requests to the B2B GraphQL API. These tokens are customer-specific and obtained after authenticating a customer. Can be used client-side or server-side.
• Customer Context: This refers to how a GraphQL request is made on behalf of a specific authenticated customer. In the BigCommerce GraphQL API, this context is provided by a session cookie in client-side requests or by a customer access token in server-side requests. In the B2B GraphQL API, the B2B Storefront Token itself provides the customer context.
• Customer Access Token: This token is obtained after authenticating a customer with the BigCommerce GraphQL API with a server-side request and is included in subsequent requests in a specialized header.

The B2B Storefront Token, the user’s BigCommerce customer ID, the B2B user ID, and the user’s B2B company ID should all be tracked in a user’s session information within your application.

Anonymous vs. Authenticated Requests

Any GraphQL request, whether to the BigCommerce GraphQL Storefront API or the B2B GraphQL API, falls into one of two categories: anonymous requests or requests made within a customer context. What distinguishes the two categories differs between the APIs.

BigCommerce GraphQL Storefront API

Every request to the GraphQL Storefront API includes a Storefront Token as a Bearer token, but the Bearer token alone does not identify a customer. A request that includes only a Bearer token, with no session cookie (client-side) or customer access token (server-side), is anonymous, and can fetch publicly available storefront data such as catalog and content. To make a request on behalf of a specific customer, add a session cookie or customer access token to establish customer context.

B2B GraphQL API

A B2B GraphQL request is anonymous when it includes no Bearer token at all. Only a few queries and mutations can be made this way, as they don’t require the context of any specific storefront user. Examples include the login mutation itself, which authenticates a user’s credentials, and the storefrontConfigs query, which fetches various store configuration settings.

Most queries and mutations deal with specific company data, and these requests require a user-specific Bearer token, the B2B Storefront Token, identifying the user on whose behalf the request is being made. Because this token is itself customer-specific, it both authenticates the request and provides the customer context.

Logging in with the BigCommerce GraphQL Storefront API

Unlike the B2B GraphQL API, the GraphQL Storefront API requires a Bearer token from the very first request. Every request, including the login mutation, must include a Storefront Token (a client-side token or a private token) as a Bearer token. This token authorizes access to the API, but it does not by itself establish customer context.

To authenticate a customer, use the login mutation with the customer’s email and password.

Example Request and Response

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

How the customer context is returned depends on where the request is made:

• Client-side: A successful login returns a session cookie that establishes the customer context for subsequent requests. This is reliable only within a Stencil storefront, where it also logs the customer into the Stencil storefront session.
• Server-side: Query the customerAccessToken field in the response. Include the returned token value in the X-Bc-Customer-Access-Token header on subsequent requests to establish customer context.

For example, a server-side request passes the customer access token in the X-Bc-Customer-Access-Token header alongside the Storefront Token:

POST https://www.example.com/graphql
Content-Type: "application/json"
Authorization: "Bearer {storefront_token}"
X-Bc-Customer-Access-Token: "{customer_access_token}"
{
    "query": "query { customer { entityId email } }"
}

In both cases, query the customer’s BigCommerce customer ID (customer.entityId) in the response. You’ll need this ID for later steps, such as exchanging credentials for a B2B Storefront Token.

Syncing with the B2B GraphQL API

Once the customer is authenticated with the GraphQL Storefront API, you can exchange that authenticated context for a B2B Storefront Token. The approach depends on whether you’re working client-side or server-side.

• Client-side: Use the Current Customer API to obtain a JWT representing the current customer session, then pass that JWT to the B2B GraphQL authorization mutation. The mutation returns a B2B Storefront Token.
• Server-side: Call the /api/io/auth/customers/storefront REST endpoint in the B2B REST Management API, passing the customer access token, to obtain a B2B Storefront Token.

Once you have the B2B Storefront Token, pass it in an Authorization header with the value Bearer {token} on subsequent B2B GraphQL requests:

POST https://api-b2b.bigcommerce.com/graphql
Accept: "application/json"
Content-Type: "application/json"
Authorization: "Bearer {token}"
{
    "query": "..."
}

Logging in with the B2B GraphQL API

To authenticate a customer directly with the B2B GraphQL API, use the login mutation with the store hash and the customer’s email and password. A successful response returns a B2B Storefront Token in login.result.token, along with the B2B user ID (user.id) and the BigCommerce customer ID (user.bcId).

Example Request and Response

mutation {
    login(
        loginData: {
            storeHash: "pki...",
            email: "user@example.com",
            password: "MyPassword123..."
        }
    ) {
        result {
            token
            user {
                id
                bcId
                firstName
                lastName
                email
            }
        }
    }
}

On subsequent B2B GraphQL requests, pass the token in an Authorization header with the value Bearer {token}:

POST https://api-b2b.bigcommerce.com/graphql
Accept: "application/json"
Content-Type: "application/json"
Authorization: "Bearer {token}"
{
    "query": "..."
}

Syncing Logins in Stencil

The B2B GraphQL login operation is independent of the standard customer session in a Stencil storefront, but the available mutations offer strategies for automatically logging a B2B user into the Stencil storefront and vice versa.

The storefrontLoginToken Field

This technique applies when a user is logged in with the B2B GraphQL API and this login needs to be synced with the Stencil storefront session.

In addition to the standard token value, the field storefrontLoginToken can be queried on a login response.

Example Request:

mutation {
    login(
        loginData: {
            ...
        }
    ) {
        result {
            storefrontLoginToken
            token
            user {
                ...
            }
        }
    }
}

This storefrontLoginToken is a Json Web Token (JWT) encoded with the B2B Edition client secret and intended for use with the BigCommerce Customer Login API. Pass this JWT value to the Customer Login endpoint to log the customer in with a Stencil storefront session. See the BigCommerce documentation for the full details.

The authorization Mutation

This technique applies when a user is already logged into a Stencil storefront session to automatically sync their login with a B2B GraphQL token.

The B2B GraphQL API makes an authorization mutation available for this purpose.

This process relies on the BigCommerce Current Customer API endpoint. While the details of this API aren’t covered here, see the BigCommerce documentation for the full details. This endpoint is used with the B2B Edition client ID (see the authentication documentation for this ID) to obtain a JWT representing the customer session. This does not need to be decoded by your application but is passed directly to the authorization mutation.

Example Request:

mutation {
    authorization(
        authData: {
            bcToken: {JWT value}
        }
    ) {
        result {
            token
        }
    }
}

The resulting token functions the same as the token obtained with login.

Syncing Logins with BigCommerce GraphQL

The B2B GraphQL storefrontToken mutation uses the B2B GraphQL API to create a standard BigCommerce GraphQL Storefront API token. Use this mutation only for client-side requests; the token it returns is not suitable for server-side use.

Obtaining the Token from the Buyer Portal

If you are working within a storefront where the B2B Buyer Portal is already integrated and is handling login for your users, you may find it useful to retrieve the token tracked by the Buyer Portal for use in your own custom client-side GraphQL queries.

This token is globally available using the following syntax:

window.b2b.utils.user.getB2BToken()

Resources

• Current Customer API
• Authentication
• Customer Access Tokens
• Get a B2B Storefront Token