Skip to main content

Overview

Why read this overview?​

Before you copy a single SDK snippet, you need to know which token your storefront should use, how that token is issued, and the security trade-offs of storing it in a browser or on the server. Elastic Path Commerce Cloud exposes several tokens types; for shopper storefronts you'll almost always rely on the implicit token + Account-Auth token pair. This page clarifies the moving parts so the task-oriented guides make sense.

1 · Token types at a glance​

TokenWho uses itTypical scopeHow it's issued
Implicit shopper tokenAny storefront: SPA, PWA, SSR, SSGRead/write carts, orders, catalog for one shoppergrant_type=implicit – no client_secret required
Account Management Auth tokenB2C and B2B flows – identifies individual shoppersImpersonate account member; access personal resourcesPOST /v2/account-members/tokens
Client-credentials (app) tokenServer-side jobs, SSR, integrationsStore-wide admin scopegrant_type=client_credentials with secret

The legacy Customer token exists for older builds; new storefronts should create Accounts + members instead.

info

All API endpoints require authentication. The implicit token is attached to every request using the Authorization: Bearer <token> header:

Authorization: Bearer 212LJ3k0i2382364HIUEjfeJB98yvH

Access tokens expire after 1 hour, requiring regeneration. The Shopper SDK can automatically handle this for you with appropriate setup.

2 · Client Credentials vs. Implicit​

According to the Elastic Path documentation:

  • implicit: Generates a token with limited, mostly read-only access. Designed for client-side browser applications (frontends).
  • client_credentials: Provides full read and write access. Used for all administrative tasks (CRUD operations) at the backend.

The distinction is important for security - never expose client_credentials tokens in browser code.

3 · Shopper Authentication​

For shopper experiences, you typically use two tokens together:

  1. An implicit access token (basic API access)
  2. An Account Management authentication token (shopper-specific resources)

Account Management authentication isn't just for B2B scenarios - it's the standard approach for any personalized shopping experience in both B2C and B2B contexts. When a customer logs into a storefront, the Account Management token identifies them and grants access to their specific data.

When using Account Management APIs, the account authentication token is set in the EP-Account-Management-Authentication-Token header, granting access to resources associated with the account: carts, orders, catalogs, and addresses.

Customer Authentication (Legacy)​

caution

Customer tokens are a legacy authentication mechanism. For new implementations, use Account-based authentication instead.

The legacy customer token is set in the X-Moltin-Customer-Token header to access customer-specific resources.

4 · Typical shopper auth flow​

Token lifecycle differences​

Implicit token:

  • Purpose: Provides basic API access to Elastic Path endpoints
  • Lifespan: Short-lived (~1 hour)
  • Renewal: Must be refreshed regularly using createAnAccessToken when expired
  • Header: Authorization: Bearer <token>
  • Scope: Limited access, mostly read permissions with some write capabilities for the current session

Account Management token:

  • Purpose: Associates requests with a specific shopper's account
  • Lifespan: Configurable per store (can be set to implement idle timeout)
  • Renewal: Can be refreshed using the refresh token provided with the initial authentication
  • Header: EP-Account-Management-Authentication-Token: <token>
  • Scope: Grants access to the shopper's personal resources (carts, orders, addresses)
info

Configurable Expiration & Idle Timeout

The Account Management Authentication Token's expiration time can be configured on a per-store basis:

  1. Store administrators can set account_management_authentication_token_timeout_secs to implement idle timeout
  2. This allows for automatic logout after periods of inactivity
  3. While users are active, their tokens should be refreshed periodically to maintain their session

The timeout setting is particularly useful for implementing security features like session timeout in B2B applications or high-security storefronts.

Working together​

Every API request requires the implicit token for base authentication. For personalized operations (viewing a user's cart, placing an order), you also need to include the Account Management token in a separate header. Think of the implicit token as your "API pass" and the Account Management token as your "personalization identifier."

Token Refresh Strategy​

For a complete authentication system, implement these refresh strategies:

Implicit token refresh:

  • Refresh before expiration (proactive) or on 401 errors (reactive)
  • Requires a new call to createAnAccessToken with grant_type=implicit

Account Management token refresh:

  • Use the refresh token provided during initial authentication
  • For self-signup flows, the initial token request with credentials provides both the token and refresh token
  • Implement idle timeout by stopping refreshes after a period of inactivity
  • See Authentication using Self Sign Up for complete implementation details

5 · Where to store the token?​

Managing both tokens​

You need to store and manage both the implicit token and the Account Management token:

  1. Implicit token - required for all API requests in the Authorization header
  2. Account Management token - required for personalized shopping in the EP-Account-Management-Authentication-Token header

Both tokens should be stored using the same security approach. The storage options below apply to both tokens.

StorageProsCons
localStoragePersist across tabs; simplestReadable by any XSS script (Auth0)
Readable cookie (Secure; SameSite=Lax)Auto-sent to same-site requestsVulnerable to CSRF (mitigate with anti-CSRF tokens) (OWASP Cheat Sheet Series)
HttpOnly cookie (server proxy)Immune to XSS; ideal for SSRJS can't read it; every request must hit server (Auth0 Community)
In-memory JS variableLeast surface area; cleared on refreshUser loses session on reload

Best practice: For a pure SPA, combine in-memory storage plus a silent token refresh (see the refresh how-to); if you already proxy API calls through your Next.js server, prefer an HttpOnly cookie.

tip

When storing both tokens, consider using a consistent naming pattern such as ep_implicit_token and ep_account_token to clearly identify each token's purpose.

6 · Token lifetime & refresh​

  • Implicit tokens default to ≈ 3600 s (1 h) (Elastic Path Documentation).
  • When the SDK gets 401 Unauthorized, refresh with a new implicit grant and retry once.
  • For long-running B2B dashboards, schedule a refresh 5 minutes before expires_in.

Refresh tokens are not issued for implicit grants, so plan on silent re-auth or redirect re-login (Auth0).

7 · Security checklist 🛡️​

  • Use HTTPS everywhere; the API rejects non-TLS.
  • Set Secure and SameSite=Lax on any cookie that carries a token.
  • Protect against XSS: Content-Security-Policy, strict lint on unescaped HTML.
  • Never include client_secret in client-side code; use implicit flow for frontends.

8 · What's next?​

Read these in order or jump straight to the task you need—this concepts page will be here whenever you need a refresher.