PAPI-3173 - Introduce private token authentication and deprecate simple token for S2S requests #1245
Conversation
…le/storefront tokens for S2S requests
There was a problem hiding this comment.
Pull request overview
This pull request introduces private tokens for server-to-server integrations with the GraphQL Storefront API and deprecates the use of storefront tokens in server-to-server contexts. The changes include new API endpoints, comprehensive documentation updates, and clear migration guidance for developers.
Changes:
- Added a new
/storefront/api-token-privateendpoint with POST and DELETE operations for creating and revoking private tokens - Added deprecation notices across API reference and documentation indicating that storefront tokens will no longer be usable statelessly in server-to-server contexts after a future deprecation date
- Updated all relevant documentation to recommend private tokens for server-to-server use cases while maintaining storefront tokens for browser-based applications
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| reference/storefront_tokens.v3.yml | Added private token endpoint definitions (create/revoke), updated descriptions to clarify token types, and added deprecation notice for storefront tokens in S2S contexts |
| docs/storefront/headless/customers.mdx | Updated to recommend private tokens with customer access tokens for headless/server-side code |
| docs/storefront/headless/channels.mdx | Clarified token usage patterns: private tokens for S2S, customer impersonation for S2S with customer data, storefront tokens for browsers |
| docs/storefront/graphql/index.mdx | Added deprecation warning for storefront tokens in S2S contexts and updated guidance to recommend private tokens |
| docs/start/authentication/graphql-storefront.mdx | Added comprehensive private tokens section with creation examples, security guidance, and updated all S2S recommendations to use private tokens |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - **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 all server-to-server integrations. Storefront tokens cannot be used statelessly in server-to-server contexts. |
There was a problem hiding this comment.
The statement "Private tokens are required for all server-to-server integrations. Storefront tokens cannot be used statelessly in server-to-server contexts" is inconsistent with the deprecation notice, which states that existing storefront tokens created before the deprecation date will continue to work in server-to-server contexts. This should be rephrased to indicate that private tokens will be required going forward, or that they are required for new integrations, rather than stating it as an absolute present requirement.
| - **Required for server-to-server:** Private tokens are required for all server-to-server integrations. Storefront tokens cannot be used statelessly in server-to-server contexts. | |
| - **Required for new server-to-server integrations:** Private tokens are required for new and future server-to-server integrations. Existing storefront tokens created before the deprecation date will continue to work in server-to-server contexts as described in the deprecation notice above. |
There was a problem hiding this comment.
But we do not want to encourage users to use strf tokens in any way.
In other words: our current users will be asked to migrate from strf token to private token (in terms of the s2s ctx).
…le/storefront tokens for S2S requests
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…on descriptions and remove private token revocation endpoint
…-token-introduction' into PAPI-3173_strf-stateless-private-token-introduction
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…rove clarity in JWT payload examples
…orrect JSON structure by nesting the token under a "data" key
…lder comments in the "meta" field for improved clarity
| 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 |
There was a problem hiding this comment.
The MDX validator flagged a syntax problem here.
| 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 |
There was a problem hiding this comment.
The MDX validator flagged a syntax problem here.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### 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-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. |
There was a problem hiding this comment.
The anchor link #create-a-private-token may not match the generated anchor from the API specification. The summary for the private token endpoint is "Create a Private API Token" (line 144 in reference/storefront_tokens.v3.yml), which would typically generate an anchor like #create-a-private-api-token, not #create-a-private-token. Please verify that the anchor link correctly matches what the documentation system generates.
| 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-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 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. |
|
|
||
| ### Create a private token | ||
|
|
||
| Use the [Create a private token](/docs/rest-authentication/tokens#create-a-private-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. |
There was a problem hiding this comment.
The anchor link #create-a-private-token may not match the generated anchor from the API specification. The summary for the private token endpoint is "Create a Private API Token" (line 144), which would typically generate an anchor like #create-a-private-api-token, not #create-a-private-token. Please verify that the anchor link correctly matches what the documentation system generates. You may need to either: 1) update the links to use #create-a-private-api-token, or 2) update the summary to "Create a Private Token" to match the anchor.
| Use the [Create a private token](/docs/rest-authentication/tokens#create-a-private-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. | |
| 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. |
| ### Endpoints | ||
|
|
||
| * [Create a storefront token](/docs/rest-authentication/tokens#create-a-token) | ||
| * [Create a private token](/docs/rest-authentication/tokens#create-a-private-token) |
There was a problem hiding this comment.
The anchor link #create-a-private-token may not match the generated anchor from the API specification. The summary for the private token endpoint is "Create a Private API Token" (line 144 in reference/storefront_tokens.v3.yml), which would typically generate an anchor like #create-a-private-api-token, not #create-a-private-token. Please verify that the anchor link correctly matches what the documentation system generates.
| * [Create a private token](/docs/rest-authentication/tokens#create-a-private-token) | |
| * [Create a private token](/docs/rest-authentication/tokens#create-a-private-api-token) |
Jira: PAPI-3173
What changed?
Release notes draft
Anything else?
Related to: https://github.com/bigcommerce/developer-center/pull/1346