UUID to JWT Token Migration in Salesforce Commerce Cloud: What Changed and How to Fix It

Salesforce deprecated UUID access token formats for API Clients in Commerce Cloud Account Manager, with a cutover effective June 15, 2023. Any API Client still configured to use UUID tokens after that date was automatically switched to JWT — and any integration that hard-codes assumptions about UUID token length or format was at risk of authentication failures.

If you're reading this because an integration started throwing auth errors, or because you're auditing API Clients before they break in production, this article covers exactly what changed, why it matters for teams running commerce integrations, and the steps to migrate your API Client configuration from UUID to JWT in Account Manager.

Why Salesforce Deprecated UUID Tokens

Salesforce framed this change as a security and reliability improvement for Commerce Cloud Account Manager. JWT (JSON Web Token) is a more standardized, verifiable token format than the legacy UUID-based access tokens, and moving all API Clients to a single token format reduces the surface area Salesforce has to support and secure long-term.

For teams maintaining custom integrations — order management, ERP sync, headless storefronts calling the Shopper API, middleware services authenticating as an API Client — this wasn't optional. Once the deprecation date passed, UUID tokens stopped being issued, and any client-side logic depending on UUID-specific behavior needed to be updated beforehand.

Who Is Affected

This change impacts any Commerce Cloud customer with API Client applications configured to use the UUID Access Token Format. That includes:

• Integration services (middleware, iPaaS, custom Node.js services) authenticating against Commerce Cloud APIs as an API Client.

• Internal tooling or scripts that call Commerce Cloud OCAPI/Shopper APIs and store or validate the token locally.

• Any code path that checks the length or structure of the token string as a form of validation — a pattern more common than teams expect in older integrations, and the main source of breakage in this migration.

Most standard OAuth flows using the Bearer token as an opaque string were unaffected by the format change itself. The real risk was in code that treated the token as a fixed-length UUID rather than as an opaque credential — which is a fragile assumption regardless of this deprecation, and worth removing from any codebase going forward.

Migration Timeline

• Before June 15, 2023: UUID and JWT formats coexisted. Customers could manually switch API Clients to JWT ahead of the deadline.

• From June 15, 2023 onward: Salesforce stopped supporting UUID tokens for API Clients. Any API Client still set to UUID was force-migrated to JWT by Salesforce.

If your team missed the manual migration window, the token format changed regardless — the risk wasn't losing authentication capability, it was breaking any code that made brittle assumptions about the old token format.

How to Switch an API Client from UUID to JWT

The migration itself is a configuration change in Account Manager, not a code rewrite — unless your integration depends on UUID-specific token handling. Steps:

1. Log in to Account Manager.

2. Click API Client. This lists all API Clients configured for your organization.

3. Filter by Token Format, select UUID to list every API Client still on the deprecated format.

4. Click into an API Client using UUID to open its configuration page.

5. Scroll to the bottom of the page and set Access Token Format to JWT.

6. Click Save, and repeat for every remaining API Client on UUID.

For teams managing more than a handful of API Clients, this is worth scripting or at least tracking in a checklist — Account Manager doesn't offer a bulk-update option, so each client is updated individually.

What Breaks (and What Doesn't) in Your Integration Code

For most API Clients, switching the token format has no impact on integration code. JWT and UUID are both passed as Bearer tokens in the Authorization header, and standard OAuth client libraries treat the token as an opaque string — they don't inspect its internal format.

The exception is any code that explicitly validates token length or structure as a UUID (typically 36 characters, hyphenated). JWTs are structurally different — longer, base64-encoded, three dot-separated segments — so any hard-coded length check or regex validation written against the old UUID format will fail once the token changes. If your team has this kind of validation anywhere in the authentication layer, it needs to be removed or rewritten before relying on JWT tokens, not after.

This is a good moment to audit for this pattern even outside the immediate deprecation: treating an access token as anything other than an opaque credential is a fragile design choice that creates exactly this kind of breakage risk whenever a provider changes its token format.

Testing the Migration

Before flipping API Clients in production, validate the change in a lower environment where possible. A useful reference for comparing UUID and JWT authentication flows side by side is available as a public Postman collection: SFB2C UUID vs JWT Postman Collection. It's a practical way to confirm your integration's auth flow works identically against both token formats before you touch the production API Client configuration.

Conclusion

This deprecation is a small configuration change with an outsized blast radius if a team's authentication code made assumptions it shouldn't have. The fix is straightforward — switch each API Client's Access Token Format to JWT in Account Manager — but the real lesson is broader: access tokens should always be treated as opaque, provider-defined strings, never validated by format or length. Teams that followed that principle already had nothing to do here; teams that didn't found out the hard way.