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
Token | Who uses it | Typical scope | How it's issued |
---|---|---|---|
Implicit shopper token | Any storefront: SPA, PWA, SSR, SSG | Read/write carts, orders, catalog for one shopper | grant_type=implicit – no client_secret required |
Account Management Auth token | B2C and B2B flows – identifies individual shoppers | Impersonate account member; access personal resources | POST /v2/account-members/tokens |
Client-credentials (app) token | Server-side jobs, SSR, integrations | Store-wide admin scope | grant_type=client_credentials with secret |
The legacy Customer token exists for older builds; new storefronts should create Accounts + members instead.
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
Account-based Authentication (Recommended)
For shopper experiences, you typically use two tokens together:
- An implicit access token (basic API access)
- 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)
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)
Configurable Expiration & Idle Timeout
The Account Management Authentication Token's expiration time can be configured on a per-store basis:
- Store administrators can set
account_management_authentication_token_timeout_secs
to implement idle timeout - This allows for automatic logout after periods of inactivity
- 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:
- Implicit token - required for all API requests in the
Authorization
header - 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.
Storage | Pros | Cons |
---|---|---|
localStorage | Persist across tabs; simplest | Readable by any XSS script (Auth0) |
Readable cookie (Secure; SameSite=Lax ) | Auto-sent to same-site requests | Vulnerable to CSRF (mitigate with anti-CSRF tokens) (OWASP Cheat Sheet Series) |
HttpOnly cookie (server proxy) | Immune to XSS; ideal for SSR | JS can't read it; every request must hit server (Auth0 Community) |
In-memory JS variable | Least surface area; cleared on refresh | User 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.
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
andSameSite=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?
- Quick-start tutorial – hands-on code for account + member + login.
- Token-management how-to – concrete storage snippets.
- OAuth Social Login – exchange Google ID-tokens via
socialLogin()
.
Read these in order or jump straight to the task you need—this concepts page will be here whenever you need a refresher.