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.
| ```json filename="Example response: Create a private token" showLineNumbers copy | ||
| { | ||
| "token": "...eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9...", | ||
| "meta": { | ||
| // ... | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The response example structure is inconsistent with the OpenAPI schema definition and the customer impersonation token response format shown elsewhere in this file. According to the Token_Full schema in the OpenAPI specification, the token should be nested under a data property. The response should be structured as: { "data": { "token": "..." }, "meta": {} } instead of { "token": "...", "meta": {} }. This same structure is used in the customer impersonation token response example at lines 382-388.
Jira: PAPI-3173
What changed?
Release notes draft
Anything else?
Related to: https://github.com/bigcommerce/developer-center/pull/1346