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"]
}
Property | Type | Description |
---|---|---|
channel_id | int | Must be a valid channel ID on the store (required) |
expires_at | int | Unix timestamp in seconds (required). Does not support milliseconds, microseconds, or nanoseconds. |
allowed_cors_origins | array[str] | Allowed origins for cross origin requests (required) |
{
"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
{
"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 /stores/{store_hash}/v3/storefront/api-token
Request
Creates a Storefront API token.
Required Scopes
Manage
Storefront API Tokens
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
allowed_cors_originsarray[string]
List of allowed domains for Cross-Origin Request Sharing. Currently accepts a maximum of two domains per created token.
channel_idinteger
requiredChannel ID for requested token
Example: 1
expires_atinteger
requiredUnix timestamp (UTC time) defining when the token should expire. Supports seconds, but does not support milliseconds, microseconds, or nanoseconds.
Example: 1885635176
example
Response
Body
dataobject
metaobject
Response metadata.
example
Revoke a Token
DELETE /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- Sf-Api-Token in header - stringrequired
An existing JWT token that you want to revoke.
example
Response
A storefront API token revocation has been scheduled.