Customer authentication
Storefront access and customer identity are separate concerns. A storefront token authorizes access to a protected project’s Storefront API; a customer access token identifies the signed-in shopper.
Never expose an Admin API key in storefront code. Treat customer access and refresh tokens as secrets, and send the access token as Authorization: Bearer <token> for authenticated customer operations.
Sign in
Call customerAccessTokenCreate with the shopper’s email and password. The payload returns an access token, refresh token, and access-token lifetime in seconds.
Use the access token to query customer and perform customer-authorized mutations. Inspect the typed payload errors before creating a local session.
Store and refresh safely
Prefer a backend-for-frontend that stores both tokens in an encrypted Secure, HttpOnly, SameSite cookie or an equivalent server-side session. Avoid putting refresh tokens in JavaScript-readable persistent storage.
Refresh with customerAccessTokenRefresh according to your session policy. Replace both stored tokens with the newly returned pair.
If refresh fails, clear the customer session and require sign-in. Do not retry indefinitely or continue making authenticated requests with an expired token.
Registration and recovery
customerRegister starts registration with an email address. Your configured webhook-driven email flow delivers the activation token used by customerActivate to set the password and customer details.
Password recovery follows the same pattern: request a token with customerPasswordResetToken, deliver it through your email workflow, then submit it with customerPasswordReset.
Use neutral confirmation copy such as “If the account exists, we sent instructions.” Do not reveal account existence through wording, logs, or custom timing differences.