菜单
Decision guide for OCAPI vs SCAPI, and practical SLAS token lifecycle guidance (guest tokens, refresh rotation, public vs private clients, and hybrid SFRA/headless auth). Use this when planning integrations or debugging auth/rate-limit issues.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Guide for using the evaluate_script tool to execute JavaScript on SFCC instances via the script debugger
Guide for creating and maintaining user-facing agent skills
Mandatory preflight for MCP server design/review/audit tasks. Defines production best practices for architecting, securing, testing, and operating TypeScript MCP servers, including transport design, schema validation, error handling, and deployment.
Register SFCC hooks via cartridge package.json and hooks.json. Use when adding hooks or troubleshooting hook registration.
Guide for implementing logging in Salesforce B2C Commerce scripts
Unified caching playbook for SFCC (page cache vs custom cache vs service response cache). Use this when improving performance, reducing external calls, designing cache keys/TTLs, or debugging stale cache behavior.
| name | sfcc-ocapi-scapi-slas |
| description | Decision guide for OCAPI vs SCAPI, and practical SLAS token lifecycle guidance (guest tokens, refresh rotation, public vs private clients, and hybrid SFRA/headless auth). Use this when planning integrations or debugging auth/rate-limit issues. |
This skill is for architecture decisions and recurring operational pitfalls:
[ ] Identify the consumer: storefront server, backend system, or headless client
[ ] For shopper APIs, prefer SCAPI + SLAS when the endpoint exists
[ ] For admin APIs, use SCAPI Admin + Account Manager (AM), not SLAS
[ ] Expect 429 + Retry-After from SLAS; implement backoff + caching
[ ] Cache SLAS tokens within the correct scope (don't request a token per API call)
[ ] Refresh tokens rotate for public clients; private clients may be reusable
[ ] Avoid refresh-token race conditions (single-flight refresh per shopper)
[ ] Choose OAuth client type correctly: public vs private
[ ] Include channel_id in guest token requests when required
Access tokens are documented at roughly 30 minutes, while refresh token validity varies by shopper type and environment. Plan caching and refresh logic around these constraints, and confirm the current values for your org.
If you request a new guest/login token repeatedly, you'll burn SLAS limits and create intermittent auth failures.
Cache tokens at the right scope:
In other words: cache aggressively, but never "globally" in a way that can mix identities.
Also cache stable endpoints (JWT/JWKS/config) where possible and honor Retry-After when SLAS returns 429.
Refresh token rotation applies to public clients, while private clients may receive reusable refresh tokens:
400 Invalid Refresh Token).If a new refresh token is returned, always store it atomically before the next request.
Operational pitfall: parallel refreshes can invalidate each other. Ensure only one refresh happens at a time per shopper (single-flight / mutex) and that the stored refresh token is updated atomically.
Choose correctly; it affects your security posture and which OAuth flows you should use. Practical default:
authorization_code_pkce (not client_credentials).client_credentials.authorization_code_pkce (public) or authorization_code / authorization_code_pkce (private).SLAS may return 409 responses when the same endpoint is called repeatedly with the same USID in a short time. This usually indicates token churn or retry storms. Reduce token issuance and serialize refresh requests.
| Symptom | Likely cause | Fix |
|---|---|---|
429 Too Many Requests + Retry-After | SLAS rate limit hit | Honor Retry-After, reuse tokens, and reduce token requests |
400 invalid_request on guest token | Missing channel_id requirement | Include channel_id on guest token requests |
400 invalid_grant or Invalid Refresh Token | Reused refresh token or wrong client type | Store the newly returned refresh token and validate client type/flow |
| 409 Conflict | Service protection due to repeated calls with same USID | Throttle calls and serialize refreshes |
| 401 Unauthorized | Access token expired or wrong audience/client | Refresh or re-auth with the correct client and scopes |
Older approach: cartridge-based bridging (e.g. plugin_slas) can introduce:
Newer approach: platform-native hybrid authentication (B2C Commerce 25.3+) reduces that integration tax, but requires the sfcc.session_bridge scope and keeping the dwsid and SLAS JWT in sync. Review required headers/cookies for your architecture before rollout.