Authentication

Introduction

In this section, we’ll explore how authentication works in the B2B GraphQL API and how to obtain valid authentication tokens.

Anonymous vs. Authenticated Requests

Any B2B GraphQL request falls into one of two categories: anonymous requests or requests requiring authentication. Which category a request falls into simply depends on the GraphQL queries/mutations included in the request.

A few queries and mutations can be made anonymously, 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. In this case, no authentication token is required for the request.

Most queries and mutations deal with specific company data, and these requests require a user-specific Bearer token identifying the user on whose behalf the request is being made.

The Authentication Process

The login Mutation

The login mutation is the key operation for GraphQL authentication. This mutation validates a user’s email and password combination, returning a secure token to use with future GraphQL requests.

All B2B users correspond with a BigCommerce customer account, so the values received by the login mutation are the same credentials the user would enter at the storefront login page. (Indeed, the Buyer Portal uses the login mutation for this operation.)

Example Request and Response

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

The key field query-able in the login response is the login.result.token field, which contains a secure, personalized, and expiring secure token if authentication was successful.

Using the Authentication Token

Once a token has been obtained with the login mutation, include an Authorization header on future GraphQL requests requiring authentication, with the value “Bearer {token}”.

Example Request:

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

All mutations and queries in the request will be executed within the context of the user and company belonging to the token, and they will also be subject to the permissions granted to the user’s role.

Token Expiration

GraphQL authentication tokens are valid for 1 day before they expire.

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

Similar to syncing authentication with a Stencil storefront session, a mechanism is available for syncing with customer authentication already performed with the standard BigCommerce GraphQL Storefront API.

The login mutation of the standard GraphQL Storefront API can be used to obtain a customer access token, which is provided in a unique header to identify the customer context for other GraphQL requests.

The Get a B2B Storefront Token endpoint available in the B2B REST Management API can be used to “exchange” this customer access token for a valid B2B GraphQL token.

Example Request and Response

POST https://api-b2b.bigcommerce.com/api/io/auth/customers/storefront
{
  "customerId": 999,
  "channelId": 1,
  "customerAccessToken": {
    "value": "<token value>",
    "expires_at": "2024-12-31T00:00:00.0Z"
  }
}

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

Client vs. Server Context

If you’re accustomed to working with the standard BigCommerce GraphQL Storefront API, you might be aware that this API sometimes requires different types of tokens for different contexts. (The Customer Impersonation Token, for example, must only be used in a server-side context, not exposed in the browser.)

B2B authentication tokens are limited to the scope of a single user and automatically subject to expiration, so they are safe to use in a client-side context. And because they do not rely on storefront cookies for establishing the user context, they are appropriate for server-side context as well. Therefore, authentication strategy in the B2B GraphQL API is identical whether you are issuing your requests from the client or from a server.

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