You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
PAPI-3173 - Introduce private token authentication and deprecate simple token for S2S requests (#1245)
Jira:
[PAPI-3173](https://bigcommercecloud.atlassian.net/browse/PAPI-3173)
## What changed?
- Introduce private tokens for server-to-server GraphQL Storefront API
use and document create/revoke REST endpoints.
- Deprecate storefront tokens for server-to-server: new storefront
tokens will no longer work statelessly in server-to-server contexts
after a future date; recommend private tokens for new s2s integrations.
- Stop recommending storefront tokens for s2s: direct server-to-server
and headless/server-side flows to private tokens (and customer access
tokens where needed).
- Clarify storefront tokens as browser-only (CORS via
allowed_cors_origins) and allow customer access tokens to be used with
either a storefront or private token.
- Update/correct GraphQL storefront API token examples to reflect
correct JSON structure by nesting the token under a "data" key.
- Document private token access scopes (Unauthenticated, Customer, B2B),
scope enforcement errors (INSUFFICIENT_ACCESS_SCOPE), and the principle
of least privilege.
## Release notes draft
- Private tokens are now available for authenticating server-to-server
requests to the GraphQL Storefront API. Use them for backend and
headless integrations instead of storefront tokens.
- Storefront tokens remain for browser-based storefronts; new storefront
tokens will stop working for server-to-server after a future date, so
use private tokens for new server-to-server integrations. [Learn
more](graphql-storefront#private-tokens).
## Anything else?
Related to: bigcommerce/developer-center#1346
[PAPI-3173]:
https://bigcommercecloud.atlassian.net/browse/PAPI-3173?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
# Authenticating requests to the GraphQL Storefront API
2
2
3
-
Authenticate GraphQL Storefront API requests using bearer tokens passed with the `Authorization` header. You can authenticate using two different kinds of tokens: [storefront tokens](#storefront-tokens) or [customer impersonation tokens](#customer-impersonation-tokens).
3
+
Authenticate GraphQL Storefront API requests using bearer tokens passed with the `Authorization` header. You can authenticate using three different kinds of tokens: [storefront tokens](#storefront-tokens), [private tokens](#private-tokens), or [customer impersonation tokens](#customer-impersonation-tokens).
Storefront tokens are most appropriate to use directly from the web browser, but you can use them in server-to-server communications. If you're creating a token for an application that will make server-to-server or proxied requests to the GraphQL Storefront API, or you work with customer data, use a [customer impersonation token](#customer-impersonation-tokens). If you only wish to query information from an anonymous shopper's perspective, use a storefront token.
18
+
Storefront tokens are designed for use directly from the web browser. They support CORS via `allowed_cors_origins` and are intended for browser-based applications. For server-to-server integrations, use [private tokens](#private-tokens) instead. If you need to work with customer data, use a [customer impersonation token](#customer-impersonation-tokens). If you only wish to query information from an anonymous shopper's perspective in a browser context, use a storefront token.
19
+
20
+
<Callouttype="warning">
21
+
**Deprecation notice (storefront tokens and server-to-server):** Storefront tokens created **after June 30th, 2026** will no longer support server-to-server (s2s) use. Storefront tokens created **on or before June 30th, 2026** will continue to support s2s calls until **March 31st, 2027**, after which s2s will no longer be supported for those tokens. Use [private tokens](#private-tokens) for server-to-server integrations.
22
+
</Callout>
19
23
20
24
### Storefront token security
21
25
22
26
Generally speaking, vanilla storefront tokens are not considered sensitive, and it is safe to expose them in web browsers. Storefront tokens can only expose information and actions that shoppers can access when they browse a storefront.
23
27
24
28
It is possible to create a long-lived token that does not expire. For greater security, we recommend creating shorter-lived tokens and rotating them periodically.
25
29
26
-
For security reasons, GraphQL Storefront API tokens are scoped to particular [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) origins, so you must supply the origin or origins on which you intend to use the token. If you have more than two origins, you will need multiple tokens. If you do not supply any CORS origins, the API will reject requests originating from web browsers, although you can still use it in other contexts. GraphQL server-to-server requests do not require `allowed_cors_origins`.
30
+
For security reasons, GraphQL Storefront API tokens are scoped to particular [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) origins, so you must supply the origin or origins on which you intend to use the token. If you have more than two origins, you will need multiple tokens.
27
31
28
32
### Create a storefront token
29
33
@@ -57,7 +61,9 @@ content-type: application/json
57
61
58
62
```json filename="Example response: Create a storefront API token" showLineNumbers copy
A customer access token is unique to an individual user's account because it represents an authenticated storefront session for GraphQL requests. You can obtain and use a customer access token only for server-to-server requests. Therefore, you must use the customer access token with a regular storefront token. A customer access token becomes invalid on all devices when you log out of a single device.
77
+
A customer access token is unique to an individual user's account because it represents an authenticated storefront session for GraphQL requests. You can obtain and use a customer access token only for server-to-server requests. Therefore, you must use the customer access token with a storefront token or private token. A customer access token becomes invalid on all devices when you log out of a single device.
72
78
73
79
<Callouttype="warning">
74
80
Do not use this token for browser-side or client-side requests.
@@ -86,7 +92,7 @@ There are two options to obtain a customer access token.
86
92
Enter your user email and password to use the login mutation. When using the login mutation in a server-to-server context, the mutation will return a customer access token in response to login actions as part of the GraphQL body instead of a cookie header. From there, you can store the customer access token in the presentation layer's session management system and send it with future GraphQL requests. If the login mutation request is from a browser, we will not return the customer access token in the body, and will instead set a cookie.
87
93
88
94
<Callouttype="info">
89
-
* Use the [Create a Token](/docs/rest-authentication/tokens#create-a-token) endpoint to generate the storefront bearer token needed to run the login mutation call.
95
+
* Use the [Create a Token](/docs/rest-authentication/tokens#create-a-token) endpoint to generate the storefront token or private token needed to run the login mutation call.
90
96
* If you request a customer access token in wrong communication context, you will receive the following error:
91
97
***Customer access token was requested in the body, but it's only returned for server-to-server requests. For browser requests it's set as an httpOnly cookie instead.***
92
98
@@ -280,6 +286,99 @@ query CustomerAttributes {
280
286
281
287
On Stencil storefronts, you can access a token at render time and pass the token to client-side code using the `{{settings.storefront_api.token}}` Handlebars property. This auto-generated token has an expiry period of 24-48 hours and will rotate before expiration.
282
288
289
+
## Private tokens
290
+
291
+
Private tokens are designed for server-to-server integrations. They are always stateless (no session required) and provide better performance for server-to-server use cases.
292
+
293
+
### Private token characteristics
294
+
295
+
-**Server-to-server only:** The API rejects private token-authenticated requests that originate from web browsers
296
+
-**Always stateless:** No session or cookie validation required
297
+
-**Required for server-to-server:** Private tokens are required for server-to-server integrations without customer impersonation. Storefront tokens cannot be used statelessly in server-to-server contexts.
298
+
-**Access scoping:** Only private tokens support access scopes (other token types do not). See [Private token access scopes](#private-token-access-scopes) below.
299
+
300
+
<Callouttype="info">
301
+
Private tokens are the recommended choice for new server-to-server integrations that don't require customer impersonation. They provide better performance and are designed specifically for stateless server-to-server use cases.
302
+
</Callout>
303
+
304
+
### Private token access scopes
305
+
306
+
Only **private tokens** use access scopes; storefront and customer access tokens do not. Scopes restrict which GraphQL fields the token can access. The token must include **all** scopes required by every field in the selection (including nested fields).
307
+
308
+
**Scopes are independent:** There is no hierarchy or inheritance. For example, `Customer` does not include or imply `Unauthenticated`—they cover different areas. You need more than one scope only when your query selects fields that require different scopes (e.g. `checkout { order { id } }` requires both Unauthenticated for `checkout` and Customer for `order`).
309
+
310
+
**Scope identifiers** (use these in the create request):
|`B2B`| Company operations (e.g. `registerCompany`). |
317
+
318
+
Scopes are required when creating a private token. The API rejects requests with no scopes. Apply the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)—request only the scopes you need.
319
+
320
+
When the token lacks a scope required by a field, the API returns a GraphQL response with `errors`. Affected fields may be `null` in `data`. The error includes `extensions.code: "INSUFFICIENT_ACCESS_SCOPE"` and `extensions.requiredScopes` (the scope identifiers required by that field):
"message": "The provided token does not include the scopes required to resolve this field.",
328
+
"path": ["company"],
329
+
"extensions": {
330
+
"code": "INSUFFICIENT_ACCESS_SCOPE",
331
+
"requiredScopes": ["B2B"]
332
+
}
333
+
}
334
+
]
335
+
}
336
+
```
337
+
338
+
### Create a private token
339
+
340
+
You **must** specify `scopes` when creating a private token. Use the [Create a private token](/docs/rest-authentication/tokens#create-a-private-api-token) REST endpoint to create private tokens. Add the [storefront API tokens creation scope](/docs/start/authentication/api-accounts#token-creation-scopes) to the [store-level or app-level API account](/docs/start/authentication/api-accounts) you use to generate tokens.
341
+
342
+
<Tabsitems={['Request', 'Response']}>
343
+
<Tab>
344
+
345
+
```http filename="Example request: Create a private token" showLineNumbers copy
346
+
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token-private
347
+
x-auth-token: {{access_token}}
348
+
accept: application/json
349
+
content-type: application/json
350
+
351
+
{
352
+
"expires_at": 1602288000, // when the token will expire, as an integer unix timestamp (in seconds)
353
+
"channel_ids": [1, 2, 3], // array of integers (must be valid channel IDs on the store)
Private tokens are sensitive and should **never** be exposed publicly. Treat them with the same care as other application secrets, such as API account access tokens. Store them securely on your server and never include them in client-side code or expose them in browser contexts.
380
+
381
+
If your token is compromised, you can use the [Revoke a token](/docs/rest-authentication/tokens#revoke-a-token) endpoint. Only use this in emergencies; do not revoke tokens unnecessarily. Instead, use a shorter expiration and allow them to expire naturally.
Copy file name to clipboardExpand all lines: docs/storefront/graphql/index.mdx
+6-2Lines changed: 6 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -691,12 +691,16 @@ Use a normal GraphQL Storefront API token. You can use an anonymous `fetch` or `
691
691
692
692
### I want to run requests from a server, and I don't need customer impersonation abilities
693
693
694
-
Use normal GraphQL Storefront API tokens. According to the [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), you should not create a token that has permissions you do not need.
694
+
For server-to-server integrations, you must use [private tokens](/docs/start/authentication/graphql-storefront#private-tokens). Private tokens are designed specifically for stateless server-to-server use cases and provide better performance. According to the [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), you should not create a token that has permissions you do not need.
695
+
696
+
<Callouttype="warning">
697
+
**Deprecation notice (storefront tokens and server-to-server):** Storefront tokens created **after June 30th, 2026** will no longer support server-to-server (s2s) use. Storefront tokens created **on or before June 30th, 2026** will continue to support s2s calls until **March 31st, 2027**, after which s2s will no longer be supported for those tokens. Use [private tokens](/docs/start/authentication/graphql-storefront#private-tokens) for server-to-server integrations.
698
+
</Callout>
695
699
696
700
697
701
### I want to run requests from a server, and I need to support customer login
698
702
699
-
The recommended option is to use a regular storefront token with a customer access token. You can exchange customer credentials for a customer access token using the login mutation and send the token on future requests using the `X-Bc-Customer-Access-Token` header. The other possible but least preferred option is to use a customer impersonation token and store it securely on your server like other secrets. When you need to run requests in the context of a particular customer (for example, if they've logged in to your application), send their BigCommerce Customer ID along with the request as the `X-Bc-Customer-Id` header. This option provides less security but is available to use.
703
+
The recommended option is to use a [private token](/docs/start/authentication/graphql-storefront#private-tokens) with a customer access token. You can exchange customer credentials for a customer access token using the login mutation and send the token on future requests using the `X-Bc-Customer-Access-Token` header. The other possible but least preferred option is to use a customer impersonation token and store it securely on your server like other secrets. When you need to run requests in the context of a particular customer (for example, if they've logged in to your application), send their BigCommerce Customer ID along with the request as the `X-Bc-Customer-Id` header. This option provides less security but is available to use.
Copy file name to clipboardExpand all lines: docs/storefront/headless/channels.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,7 @@ Optionally, you can add a 3P SSL certificate for the checkout domain by sending
41
41
42
42
### Create tokens for the GraphQL Storefront API
43
43
44
-
After setting up the channel, you're almost ready to authenticate cross-origin requests to the GraphQL Storefront API. You can [Create customer impersonation tokens](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) for most headless or server-to-server interactions, or [Storefront tokens](/docs/rest-authentication/tokens#create-a-token) for static frontend site interactions. Use your new channel ID and, where required, supply your channel site as an allowed_cors_origin; otherwise, your requests will be rejected.
44
+
After setting up the channel, you're almost ready to authenticate cross-origin requests to the GraphQL Storefront API. For server-to-server interactions, use [private tokens](/docs/rest-authentication/tokens#create-a-private-api-token). For customer impersonation in server-to-server contexts, use [customer impersonation tokens](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token). For browser-based applications, use [Storefront tokens](/docs/rest-authentication/tokens#create-a-token). Use your new channel ID and, where required, supply your channel site as an allowed_cors_origin for storefront tokens; otherwise, your requests will be rejected.
45
45
46
46
After you have a token, you're ready to get started using the [GraphQL Storefront API](/docs/storefront/graphql).
Copy file name to clipboardExpand all lines: docs/storefront/headless/customers.mdx
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,15 +19,15 @@ When you sign in a customer using the login mutation, subsequent queries to the
19
19
20
20
### Headless and server-side sign-in
21
21
22
-
To make queries from the perspective of a particular customer using headless or server-side code, use [customer access tokens](/docs/start/authentication/graphql-storefront#customer-access-tokens)and [storefront tokens](/docs/start/authentication/graphql-storefront#storefront-tokens). Then, use the customer access token in the `X-Bc-Customer-Access-Token` header.
22
+
To make queries from the perspective of a particular customer using headless or server-side code, use [customer access tokens](/docs/start/authentication/graphql-storefront#customer-access-tokens)with [private tokens](/docs/start/authentication/graphql-storefront#private-tokens). Then, use the customer access token in the `X-Bc-Customer-Access-Token` header.
23
23
24
24
We recommend using the login mutation and customer access token because this combination is more secure. In addition, there is a seamless redirection and synchronization between headless storefronts and hosted checkouts, which allow for transferring session details, such as customer and cart data, across various contexts.
25
25
26
26
## Customer single sign-on
27
27
28
28
If using the customer access token, then you just need to use the `createCartRedirectUrls` mutation and use the redirectUrl provided there. It will be a session sync link that will copy data from the headless storefront to the BigCommerce-hosted page. This approach simplifies session synchronization and offers consistent login states.
@@ -43,13 +43,13 @@ The other option is when a customer signs in to your headless storefront and you
43
43
44
44
You can sign a customer in to an embedded checkout by using the session-sync URL from the [createCartRedirectUrls mutation](https://developer.bigcommerce.com/graphql-storefront/reference#definition-CartMutations).
0 commit comments