PAPI-3173 - Introduce private token authentication and deprecate simple token for S2S requests

docs/start/authentication/graphql-storefront.mdx

@@ -1,6 +1,6 @@
 # Authenticating requests to the GraphQL Storefront API
 
-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).
+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).
 
 ```http filename="Example request configuration" showLineNumbers copy
 POST https://your_store.example.com/graphql
@@ -15,15 +15,19 @@ Content-Type: application/json
 
 ## Storefront 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.
+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.
+
+<Callout type="warning">
+**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.
+</Callout>
 
 ### Storefront token security
 
 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.
 
 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.
 
-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`.
+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.
 
 ### Create a storefront token
 
@@ -57,7 +61,9 @@ content-type: application/json
 
 ```json filename="Example response: Create a storefront API token" showLineNumbers copy
 {
-  "token": "...eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9...",
+  "data": {
+    "token": "...eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9..."
+  },
   "meta": {
     // ...
   }
@@ -68,7 +74,7 @@ content-type: application/json
 
 #### Customer access tokens
 
-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.
+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.
 
 <Callout type="warning">
 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.
 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.
 
 <Callout type="info">
-* 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.
+* 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.
 * If you request a customer access token in wrong communication context, you will receive the following error:
     ***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.***
 
@@ -280,6 +286,99 @@ query CustomerAttributes {
 
 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.
 
+## Private tokens
+
+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.
+
+### Private token characteristics
+
+- **Server-to-server only:** The API rejects private token-authenticated requests that originate from web browsers
+- **Always stateless:** No session or cookie validation required
+- **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.
+- **Access scoping:** Only private tokens support access scopes (other token types do not). See [Private token access scopes](#private-token-access-scopes) below.
+
+<Callout type="info">
+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.
+</Callout>
+
+### Private token access scopes
+
+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).
+
+**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`).
+
+**Scope identifiers** (use these in the create request):
+
+| Scope | Use |
+|-------|-----|
+| `Unauthenticated` | Store, channel, catalog, products, content, cart, checkout (except nested `order`), wishlist create/public, analytics, payment, newsletter. |
+| `Customer` | Customer identity, orders, login/logout, session sync, registration (`registerCustomer`), customer wishlists, cart assignment, order messages. |
+| `B2B` | Company operations (e.g. `registerCompany`). |
+
+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.
+
+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):
+
+```json filename="Example: insufficient access scope error" showLineNumbers copy
+{
+  "data": null,
+  "errors": [
+    {
+      "message": "The provided token does not include the scopes required to resolve this field.",
+      "path": ["company"],
+      "extensions": {
+        "code": "INSUFFICIENT_ACCESS_SCOPE",
+        "requiredScopes": ["B2B"]
+      }
+    }
+  ]
+}
+```
+
+### Create a private token
+
+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.
+
+<Tabs items={['Request', 'Response']}>
+<Tab>
+
+```http filename="Example request: Create a private token" showLineNumbers copy
+POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token-private
+x-auth-token: {{access_token}}
+accept: application/json
+content-type: application/json
+
+{
+  "expires_at": 1602288000,   // when the token will expire, as an integer unix timestamp (in seconds)
+  "channel_ids": [1, 2, 3],  // array of integers (must be valid channel IDs on the store)
+  "scopes": [                 // access scope identifiers (required)
+    "Unauthenticated",
+    "Customer",
+    "B2B"
+  ]
+}
+```
+</Tab>
+<Tab>
+
+```json filename="Example response: Create a private token" showLineNumbers copy
+{
+  "data": {
+    "token": "...eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9..."
+  },
+  "meta": {
+    // ...
+  }
+}
+```
+</Tab>
+</Tabs>
+
+### Private token security
+
+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.
+
+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.
 
 ## Customer impersonation tokens
 
@@ -325,11 +424,12 @@ Content-Type: application/json
 
 ```json filename="Example response: Create a customer impersonation token" showLineNumbers copy
 {
-  "data":
-  {
-    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+  "data": {
+    "token": "...eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9..."
   },
-  "meta": {}
+  "meta": {
+    // ...
+  }
 }
 ```
 </Tab>
@@ -466,6 +566,7 @@ If you're signed out, the system reverts to a "guest" version of the cart, allow
 ### Endpoints
 
 * [Create a storefront token](/docs/rest-authentication/tokens#create-a-token)
+* [Create a private token](/docs/rest-authentication/tokens#create-a-private-api-token)
 * [Create a customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token)
 * [Revoke a token](/docs/rest-authentication/tokens#revoke-a-token)
 * [Customer Login API](/docs/rest-authentication/customer-login)

docs/storefront/graphql/index.mdx

@@ -691,12 +691,16 @@ Use a normal GraphQL Storefront API token. You can use an anonymous `fetch` or `
 
 ### I want to run requests from a server, and I don't need customer impersonation abilities
 
-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.
+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.
+
+<Callout type="warning">
+**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.
+</Callout>
 
 
 ### I want to run requests from a server, and I need to support customer login
 
-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.
+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.
 
 ### I want a list of GraphQL error messages
 

docs/storefront/headless/channels.mdx

@@ -41,7 +41,7 @@ Optionally, you can add a 3P SSL certificate for the checkout domain by sending
 
 ### Create tokens for the GraphQL Storefront API
 
-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.
+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.
 
 After you have a token, you're ready to get started using the [GraphQL Storefront API](/docs/storefront/graphql).
 

docs/storefront/headless/customers.mdx

@@ -19,15 +19,15 @@ When you sign in a customer using the login mutation, subsequent queries to the
 
 ### Headless and server-side sign-in
 
-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.
+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.
 
 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.
 
 ## Customer single sign-on
 
 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.
 
-```js "Generate redirectUrl example" showLineNumbers copy
+```graphql "Generate redirectUrl example" showLineNumbers copy
 mutation createRedirectUrl($input: CreateCartRedirectUrlsInput!) {
   cart {
     createCartRedirectUrls(input: $input) {
@@ -43,13 +43,13 @@ The other option is when a customer signs in to your headless storefront and you
 
 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).
 
-```js filename="Example JWT payload" showLineNumbers copy
+```json filename="Example JWT payload" showLineNumbers copy
 {
-  "iss": {{CLIENT_ID}},
+  "iss": "{{CLIENT_ID}}",
   "iat": 1535393113,
-  "jti": {{UUID}},
+  "jti": "{{UUID}}",
   "operation": "customer_login",
-  "store_hash": {{STORE_HASH}},
+  "store_hash": "{{STORE_HASH}}",
   "customer_id": {{CUSTOMER_ID}},
   "channel_id": {{CHANNEL_ID}},
   "redirect_to": "/cart.php?embedded=1&action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",