Authentication and sessions

The three credentials — storefront access token, visitor session, customer token — and the exact sequence to wire them.

Storefront GraphQL uses three credentials, layered: the storefront ACCESS TOKEN authorizes you to talk to the store at all; a VISITOR SESSION gives your anonymous shopper an identity that carts, wishlists, consent, and review photos bind to; a CUSTOMER TOKEN upgrades that shopper to a logged-in account. Most apps use all three.

1. The storefront access token#

Issued by the merchant in StoreAdmin (Settings → Tokens), scoped to one storefront and one API version. Send it on EVERY request as X-Storefront-Access-Token — the endpoint URL never changes across API versions because the token pins the version. Requests without it are rejected before anything executes. This is also why the API works on password-protected stores: the password page gates browsing; the token gates the API.

2. The visitor session#

graphql

mutation Start {
  visitorSessionCreate {
    token
    userErrors { code message }
  }
}

Create one session per visitor, store the token client-side, and send it as X-Tringify-Session-Token on every subsequent request. This is the identity that guest state binds to: the cart, the wishlist, consent choices, review-photo uploads. Check runtimeContext.session.expiresAt and call visitorSessionRenew before it lapses — a lapsed session means a fresh, empty guest. Calling visitorSessionCreate while already presenting a valid session is rejected (SESSION_ALREADY_ACTIVE): renew to extend, or drop the header to deliberately start over.

3. Customer accounts#

graphql

mutation SendCode($input: CustomerAuthCodeSendInput!) {
  customerAuthCodeSend(input: $input) {
    userErrors { code message }
  }
}

mutation Login($input: CustomerLoginInput!) {
  customerLogin(input: $input) {
    customerAccessToken { token expiresAt }
    userErrors { code message }
  }
}

There are NO customer passwords — the code is the only credential. Request one with customerAuthCodeSend (provider EMAIL or PHONE); the server derives whether the identifier is a LOGIN or a REGISTER and returns it as mode, so your UI never asks the shopper which they are. Complete with customerLogin or customerRegister carrying the code (register additionally takes name fields). Registration is gated by the store's self-registration setting. After completion, send the returned token as X-Customer-Access-Token alongside your session token.

Keep sending BOTH tokens after login. The guest state your visitor built — cart, consent, uploaded review photos — follows them into the account; features that require a purchase history (verified review badges, purchase-gated review submission) unlock through the customer token.

The headers, together#

Header	Send when	You get
X-Storefront-Access-Token	Always	Access to the store's GraphQL at your pinned API version.
X-Tringify-Session-Token	From your second request on	Guest identity: cart, wishlist, consent, review photos.
X-Customer-Access-Token	After login	Customer identity: account data, verified reviews, purchase-gated features.