Mastering Shopify’s Customer Account API: Secure Auth in Hydrogen

Introduction

Shopify’s new Customer Account API is the foundation of identity in Hydrogen storefronts. It replaces the legacy Liquid-based customer auth, giving developers OAuth2 flows, modern session handling, and checkout continuity.

But it also brings new challenges: secure implementation, local dev setup, and gaps like Multipass SSO support. This post dives deep into how to use the Customer Account API safely and effectively.

Why It Matters

• 🛒 Unified identity → one customer object for checkout, orders, loyalty.
• 🔑 Modern OAuth2 with PKCE → industry-standard security.
• 🌍 Cross-platform consistency → works across Hydrogen, mobile apps, and B2B portals.

👉 The API shifts customer identity from “theme sessions” to real OAuth flows.

Secure OAuth2 with PKCE

Hydrogen apps authenticate customers with OAuth2 + PKCE.

Flow Overview

1. Redirect user to Shopify’s auth endpoint.
2. Exchange code + PKCE verifier for tokens.
3. Store tokens in HttpOnly cookies.
4. Use refresh tokens for session continuity.

const tokenResponse = await fetch(TOKEN_ENDPOINT, { method: "POST", body: { grant_type: "authorization_code", code: authCode, code_verifier: pkceVerifier, redirect_uri: REDIRECT_URI, }, });

Local Dev Pitfalls

• HTTPS required → must use ngrok or similar to tunnel localhost.
• Redirect URIs → mismatches cause silent failures.
• Token storage → avoid localStorage (XSS risk). Use HttpOnly cookies.

Gaps & Limitations

• Multipass SSO → not yet supported in new Customer API.
• Third-party identity providers → need custom bridging (Firebase/Supabase).
• Token refresh → devs must handle rotation and sync with Shopify sessions.

When to Use Customer API vs Legacy

• Use Customer Account API if:
  • You’re building Hydrogen storefronts.
  • You need OAuth2 compatibility across devices.
  • You want modern token/session security.
• Use legacy Liquid auth if:
  • Store still runs primarily on Dawn.
  • Migration timelines prevent new API adoption.

Case Example: B2B Portal

• Apparel brand needed unified login for Hydrogen storefront + wholesale portal.
• Used Customer Account API for identity, bridged Firebase for portal SSO.
• Outcome: single login across storefront + portal, secure token refresh.

Guardrails

• ✅ Always use PKCE with secure storage (HttpOnly cookies).
• ✅ Handle refresh + logout flows to avoid token drift.
• ✅ Document redirect URIs in local + prod.
• ✅ Train teams on OAuth2 basics — not just Shopify specifics.

Conclusion

The Customer Account API is Shopify’s future for customer identity. It requires more setup than legacy Liquid auth, but delivers modern OAuth2 security, better session continuity, and flexibility across platforms.

Think of it as Shopify moving from “session hacks” to “identity done right.”