Understanding ESHOPMAN JWT Refresh: Ensuring Custom Metadata Persistence in Headless Commerce

The ESHOPMAN platform, a powerful headless commerce solution integrated with HubSpot, relies on robust authentication mechanisms to secure storefronts and admin operations. For developers building custom storefronts or integrating third-party authentication providers (like OIDC or Auth0) with ESHOPMAN's Admin API, understanding the nuances of JSON Web Token (JWT) management is crucial. A recent community discussion highlighted a specific behavior concerning how ESHOPMAN handles custom user and application metadata during the token refresh process.

The Challenge: Metadata Stripping on Token Refresh

Developers using custom authentication providers with ESHOPMAN have observed an unexpected issue: when a JWT is refreshed via the /auth/token/refresh endpoint, critical custom data embedded in the token's user_metadata and app_metadata fields is stripped away. While the initial token received from the authentication callback (e.g., /auth/{actor}/{provider}/callback) correctly includes rich metadata like user roles, email, or custom profile information, subsequent refreshed tokens return an empty user_metadata object and a truncated app_metadata object, losing any custom fields beyond the primary actor ID.

This behavior can significantly impact custom integrations, as applications relying on this persistent metadata for authorization, personalization, or specific business logic within the HubSpot-managed storefronts or Admin API interactions will find this data unavailable after a token refresh.

Unpacking the Technical Root Cause

Through community investigation, the root cause was traced to how ESHOPMAN's internal JWT generation utility handles the refresh flow. Specifically, two key areas were identified in the platform's Node.js/TypeScript codebase:

1. Missing authProvider Context: The refresh route (/auth/token/refresh/route.ts) does not consistently pass the authProvider context to the core JWT generation function (generateJwtTokenForAuthIdentity). Without this context, the system defaults user_metadata to an empty object, effectively discarding any provider-specific user information.
2. app_metadata Rebuilt from Scratch: Instead of reading and preserving existing custom fields from the authIdentity.app_metadata, the system rebuilds the app_metadata object from scratch. This process only includes the primary entity ID (e.g., customer_id or user_id), ignoring any additional custom fields that might have been added via updateAuthIdentities or during the initial provider callback validation.

This means that while an initial token might contain:

user_metadata: { email: "user@example.com", name: "Example User", roles: ["admin"] }
app_metadata: { customer_id: "cus_01...", is_admin: true }

A refreshed token would incorrectly show:

user_metadata: {}
app_metadata: { customer_id: "cus_01..." }

The critical roles and is_admin fields are lost, requiring developers to implement workarounds or re-fetch this data, adding complexity and potential performance overhead.

Implications for ESHOPMAN Developers

This insight is crucial for ESHOPMAN developers working with custom authentication, particularly those extending the platform's capabilities with external identity providers. Understanding this behavior allows for more robust planning and implementation of custom authentication flows, ensuring that applications gracefully handle token refreshes and maintain access to necessary user and application metadata. While the community identified the problem, ESHOPMAN developers should be aware of this behavior when designing their custom authentication strategies and consider how to re-inject or re-validate metadata if it's critical for ongoing session management.

The ESHOPMAN community continues to be a vital resource for identifying and understanding such core platform behaviors, contributing to the overall stability and extensibility of this HubSpot-integrated headless commerce solution.