Dev Center
Dev Center
API Docs
API Reference
Theme Docs
Tools
Library
Blog
Changelog
My Apps
Create Account
No results found.
Storefront APIs
Customer Login SSO
GraphQL Storefront API
graphql
Management APIs
API Token
Customer Impersonation Token
Webhook Callbacks
Provider APIs

Storefront Token

  • Host: api.bigcommerce.com/stores/store_hash/v3
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json

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

Authentication

Authenticate requests by including an OAuth access_token in the request header.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/channels
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}

OAuth scopes

UI Name Permission Parameter
Storefront API Customer Impersonation Tokens manage store_storefront_api_customer_impersonation
Storefront API Tokens manage store_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"
  ]
}
Property Type Description
channel_id int Must be a valid channel ID on the store (required)
expires_at int Unix timestamp (required)
allowed_cors_origins array[str] Allowed origins for cross origin requests (required)

Open in Request Runner

Response:

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

Customer impersonation tokens

Generate tokens for use in server-to-server requests to 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}}
X-Bc-Customer-Id: {{CUSTOMER_ID}}

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}"
}

Note

  • 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, they 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