BigCommerce
Storefront Authentication
GraphQL Storefront Tokens

Storefront Token

Get and manage tokens used to authenticate cross-origin requests to the GraphQL Storefront API.

API tokens

Generate tokens (JWT) for authenticating cross-origin requests to the GraphQL Storefront API. To create a token, send a POST request to /stores/{{STORE_HASH}}/v3/storefront/api-token.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "channel_id": 1,
  "expires_at": 1602288000,
  "allowed_cors_origins": 
    ["https://store.example.com"]
  
}
PropertyTypeDescription
channel_idintMust be a valid channel ID on the store (required)
expires_atintUnix timestamp in seconds (required). Does not support milliseconds, microseconds, or nanoseconds.
allowed_cors_originsarray[str]Allowed origins for cross origin requests (required)

Response:

{
  "token":"...eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9...",
  "meta": {
    // ...
  }
}

Customer impersonation tokens

Generate tokens that can make queries from the perspective of a particular customer in headless or server-side code using the GraphQL Storefront API. To create a customer impersonation token, send a POST request to /v3/storefront/api-token-customer-impersonation.

POST https://api.bigcommerce.com/stores/{STORE_HASH}/v3/storefront/api-token-customer-impersonation
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

Response:

{
  "data":
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  }
  "meta": {}
}

Customer impersonation token authenticated requests made to the GraphQL API receive store information from the perspective of the customer with the ID specified in the X-Bc-Customer-Id header sent with the GraphQL POST request. Pricing, product availability, customer account, and customer details will be reflected. Consider this sample request using a customer impersonation token to run a request in the context of customer ID 123.

POST https://store.example.com/graphql
Authorization: Bearer {{CUSTOMER_IMPERSONATION_TOKEN}}
X-Bc-Customer-Id: 123
 
{
    "query": "query CustomerInformation {\n  customer {\n    firstName\n    lastName\n    email\n  }\n}"
}

Warning

  • Customer impersonation tokens should never be exposed publicly, for example, to JavaScript or HTML. These tokens should not be used for frontend requests.
  • Unlike normal GraphQL API tokens, these tokens are sensitive and should be treated like secrets, just as you might treat an OAuth token.
  • Attempts to run requests using these tokens from a web browser will be rejected.

Revoking tokens

To revoke a token, send a DELETE request to /v3/storefront/api-token.

DELETE /stores/{{STORE_HASH}}/v3/storefront/api-token-customer-impersonation
host: api.bigcommerce.com
x-Auth-Token: {{ACCESS_TOKEN}}
Sf-Api-Token: {{CUSTOMER_ID}}

Additional information

Create a Token

POST /storefront/api-token

Request

Creates a Storefront API token.

Required Scopes

  • Manage Storefront API Tokens

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

application/json
  • allowed_cors_origins
    array[string]

    List of allowed domains for Cross-Origin Request Sharing. Currently only accepts a single element.

  • channel_id
    integer
    required

    Channel ID for requested token

    Example: 1

  • expires_at
    integer
    required

    Unix timestamp (UTC time) defining when the token should expire. Supports seconds, but does not support milliseconds, microseconds, or nanoseconds.

    Example: 1885635176

    example

    Response

    Body

    object | application/json
    • data
      object

    • meta
      object

      Response metadata.

    example

    Revoke a Token

    DELETE /storefront/api-token

    Request

    Revoke access for a Storefront API token. Only revoke compromised tokens under emergency situations. Let uncompromised short-lived tokens expire naturally, as you do not need to revoke these.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string - required

      The MIME type of the response body.

    • Sf-Api-Token in header - string - required

      An existing JWT token that you want to revoke.

    example

    Response

    A storefront API token revocation has been scheduled.

    Did you find what you were looking for?