Storefront Customer Auth

Two planes, not two auth options on one plane

A buyer session is not a weaker version of a merchant API key, and it can never be used as one. The two are isolated structurally, not by convention:

Buyer routes live at a bare /v1/storefront/* — never under /api/. A buyer access token presented to any merchant route (/api/v1/orders, etc.) is never even parsed; the merchant auth middleware only runs on /api/ and /mcp paths, so it never sees a storefront request in the first place. The reverse holds too: a merchant sk_*/pk_* key cannot be used against /v1/storefront/* — those routes require a buyer session (or, for the credential routes below, none at all).

sequenceDiagram
  participant B as Buyer Browser
  participant T as Throttle
  participant M as Your Backend
  B->>T: POST /v1/storefront/auth/login { email, password }
  note over B,T: X-API-Key: pk_* + Origin header
  T-->>B: { accessToken, refreshToken, customer }
  B->>T: GET /v1/storefront/me/orders
  note over B,T: Authorization: Bearer accessToken
  T-->>B: { data: [...] } (request.buyer, never request.auth)
  M->>T: GET /api/v1/orders
  note over M,T: X-API-Key: sk_* — a different plane entirely

Turning it on

A merchant enables customer accounts per application, per environment, via PATCH /api/v1/applications/{applicationId}/auth-settings (see Customer Accounts Settings in the API reference). Until enabled is true, every /v1/storefront/* route returns 404 auth_not_enabled — a disabled surface does not confirm it exists.

Every request also carries the storefront's existing publishable pk_* key as X-API-Key — the same key already used for shipping quotes and tax calculations — plus an Origin header, checked against the application's allowedOrigins list (the same list configured via PUT /api/v1/embed-config, not a separate buyer-auth setting).

Tokens and sessions

Login and registration return a short-lived access token and a longer-lived refresh token. Keep the access token in memory only — never write it to storage — and send it as Authorization: Bearer {accessToken} on every authenticated call.

const res = await fetch('https://api.usethrottle.dev/v1/storefront/auth/register', {
  method: 'POST',
  headers: {
    'X-API-Key': publishableKey, // pk_*
    'Content-Type': 'application/json',
    Origin: 'https://shop.example.com', // must be in allowedOrigins
  },
  body: JSON.stringify({ email, password }),
});
// 201 { data: { accessToken, expiresAt, refreshToken, customer } } — new account
// 202 { data: { status: 'pending' } } — email already has credentials; no session issued
// 400 { error: { code: 'weak_password', message } }

{
  "data": {
    "accessToken": "eyJhbGciOi...",
    "expiresAt": "2026-09-12T18:10:00.000Z",
    "refreshToken": "rt_bGl2ZS1zZXNzaW9uLWlk.9vQ2f...",
    "customer": {
      "id": "cus_51...",
      "email": "buyer@example.com",
      "emailVerified": false
    }
  }
}

// Single-flight this — see the callout below. Never fire one refresh per
// failed request; queue concurrent 401s behind one in-flight refresh call.
const res = await fetch('https://api.usethrottle.dev/v1/storefront/auth/refresh', {
  method: 'POST',
  headers: { 'X-API-Key': publishableKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({ refreshToken }),
});
// 200 { data: { accessToken, expiresAt, refreshToken, customer } } — refreshToken ROTATES;
//     store the new one and discard the old one immediately.
// 401 { error: { code: 'session_revoked' } } — expired, revoked, or replayed

Reads trust the JWT; writes verify the session row. A GET is accepted on signature and expiry alone. Any POST/PATCH/ DELETE, plus every verified- or step-up-gated route regardless of method, additionally loads the session row and checks it is not revoked and the credential's session epoch still matches. The accepted tradeoff: after a merchant revokes a buyer's sessions, a stolen access token can still be used to read that buyer's data for up to its remaining 600-second lifetime. It cannot write anything in that window — no order, no address change, no card removal, no subscription action.

Session lifecycle

Step-up: proving the password again for destructive actions

A handful of actions require a fresh step-up proof, obtained by calling POST /v1/storefront/auth/step-up with the current password and presenting the returned stepUpToken as X-Step-Up alongside the normal bearer token. Missing or expired returns 403 step_up_required.

// 1. Obtain a step-up proof for a destructive action
const stepUp = await fetch('https://api.usethrottle.dev/v1/storefront/auth/step-up', {
  method: 'POST',
  headers: {
    'X-API-Key': publishableKey,
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ password }),
});
const { data } = await stepUp.json(); // { stepUpToken, expiresIn: 300 }

// 2. Present it alongside the access token on the destructive call
await fetch(`https://api.usethrottle.dev/v1/storefront/me/payment-methods/${id}`, {
  method: 'DELETE',
  headers: {
    'X-API-Key': publishableKey,
    Authorization: `Bearer ${accessToken}`,
    'X-Step-Up': data.stepUpToken,
  },
});

Email verification and the claim cutoff

Registration issues a session immediately — a buyer does not wait on an email round trip before they can browse or check out. An unverified session can do almost everything: browse, use a cart, check out, place an order, and manage addresses created after registering. It is refused with 403 verification_required on every saved-payment-method route, on changing the account email, and on every subscription write.

Endpoint reference

All routes below are under /v1/storefront (for example, /v1/storefront/auth/login). All require an X-API-Key publishable key and an allowed Origin. "Session" means a valid Authorization: Bearer {accessToken}.

No session required

Session required

Cart claim and the retirement of X-Customer-Id

Before this feature, a storefront asserted a cart's owner with an X-Customer-Id header sent on the merchant pk_* key. Because a publishable key is, by construction, readable in a browser's page source, that header let any visitor to any storefront name any customer id on that application and be treated as them — there was no proof of identity in the buyer path at all.

POST /v1/storefront/me/carts/{cartId}/claim replaces the assertion with proof: the browser authenticates to the buyer plane, and the server — not the request body — writes the buyer's own customerId onto the cart. Existing cart and checkout routes then proceed unchanged on the pk_* key, with the cart already bound, prefilling saved addresses and cards exactly as a merchant-set customer does today.

// After the buyer logs in (or right after registration), bind their existing
// anonymous cart to the account so checkout picks up saved addresses and cards.
await fetch(`https://api.usethrottle.dev/v1/storefront/me/carts/${cartId}/claim`, {
  method: 'POST',
  headers: { 'X-API-Key': publishableKey, Authorization: `Bearer ${accessToken}` },
});
// 200 { data: { cartId, customerId } }
// 404 { error: { code: 'not_found' } } — cart belongs to another application/environment
// 409 { error: { code: 'cart_already_claimed' } } — cart is bound to a different customer

Deprecation timeline

• Now (GA 2026-09-12): X-Customer-Id still works on both key types. On a publishable key, a request that sends it gets Deprecation and Sunset response headers, and the API key id is logged server-side so a merchant can find which storefront still sends it.
• Sunset + 90 days (2026-12-11): X-Customer-Id is rejected on publishable keys with 403 header_not_permitted. Migrate any browser code that sends it to the cart-claim flow above before this date.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Fri, 11 Dec 2026 00:00:00 GMT
Link: <https://usethrottle.dev/docs/developers/storefront-auth#cart-claim>; rel="deprecation"

Error reference

Webhook events

Four events cover the buyer-auth lifecycle, gated behind the same customers:read scope as the existing customer.* family. Login is deliberately excluded — a webhook firing on every sign-in would dominate delivery volume without being an event a merchant needs to react to.

Each uses the standard delivery envelope — see the webhooks payload reference for the full envelope shape, signature verification, and retry behaviour. Types are in @usethrottle/webhook-types like every other event.

SDK: @usethrottle/auth

A headless client wraps every route above — silent refresh, single-flight and cross-tab safe refresh, retry-once-on-401 — plus a React provider, six account hooks, and five drop-in forms, matching the pattern @usethrottle/payment-methods already follows for saved cards. This section covers only the quick start; see the package README for the full API (all six hooks, step-up, errors, storage adapters) and the endpoint reference above for the raw HTTP contract it wraps.

npm install @usethrottle/auth

React is a peer dependency and optional — the core client ( createThrottleAuth, createAccount) works with no React installed.

import { ThrottleAuthProvider } from '@usethrottle/auth/react';

export function App({ publishableKey }: { publishableKey: string }) {
  return (
    <ThrottleAuthProvider publishableKey={publishableKey}>
      <StorefrontAccount />
    </ThrottleAuthProvider>
  );
}

import { SignInForm } from '@usethrottle/auth/forms';
import { useAuth } from '@usethrottle/auth/react';

function SignInPage() {
  const { isAuthenticated } = useAuth();
  if (isAuthenticated) return <p>You are signed in.</p>;
  return <SignInForm onSuccess={() => { window.location.href = '/account'; }} />;
}

import { useAuth, useOrders } from '@usethrottle/auth/react';
import { VerifyEmailPanel } from '@usethrottle/auth/forms';

function OrderHistory() {
  const { isAuthenticated, emailVerified } = useAuth();
  const { data: orders, isLoading } = useOrders();
  if (!isAuthenticated) return null;
  return (
    <>
      {!emailVerified && <VerifyEmailPanel />}
      {isLoading ? <p>Loading…</p> : orders.map((o) => <p key={o.id}>{o.orderNumber}</p>)}
    </>
  );
}

Drop-in components: @usethrottle/auth/components

The hooks above are headless — you build the UI. The ./components entry point is the other option: prebuilt, restylable React components that render inside your own storefront, so a buyer never leaves your site to sign in or read their order history. Same package, same session, same routes underneath.

npm install @usethrottle/auth
# React and react-dom are peer dependencies of this entry point

// app/providers.tsx
'use client';
import { ThrottleProvider } from '@usethrottle/auth/components';
import '@usethrottle/auth/styles.css'; // or let the provider inject it

export function Providers({ children }) {
  return (
    <ThrottleProvider
      publishableKey={process.env.NEXT_PUBLIC_THROTTLE_PUBLISHABLE_KEY}
      baseUrl="https://api.usethrottle.dev"
      appearance={{
        variables: {
          colorPrimary: '#9a3412',
          colorPrimaryForeground: '#ffffff', // set BOTH — see the note below
        },
      }}
    >
      {children}
    </ThrottleProvider>
  );
}

import {
  SignedIn, SignedOut, SignInButton, UserButton, AccountDashboard,
} from '@usethrottle/auth/components';

// In your storefront header
<SignedOut><SignInButton /></SignedOut>
<SignedIn><UserButton afterSignOutUrl="/" /></SignedIn>

// On /account
<SignedIn><AccountDashboard routing="hash" /></SignedIn>

Every panel is also exported individually (OrdersPanel, AddressesPanel, …) if you want your own shell around them.

Theming

Three levels, from least to most invasive: CSS custom properties via appearance.variables, your own classNames on any part via appearance.elements, and whole-component replacement via appearance.components. Every shipped rule is a single-class selector, so a className you pass wins on source order rather than losing to specificity.

Checkout interruption

The case these components exist for is a buyer stopped mid-purchase. Render the auth flow inline where they already are, rather than sending them to a separate page — and pair it with cart claim so the cart they built anonymously follows them into the session.

// The flow the components exist for: a buyer stopped mid-purchase.
// Render the auth card inline — the cart is already full, so navigating
// away to a separate sign-in page is what loses the sale.
import { SignedIn, SignedOut, AuthFlow } from '@usethrottle/auth/components';

<SignedOut>
  <p>Sign in to finish your order — your cart stays exactly as it is.</p>
  <AuthFlow />
</SignedOut>
<SignedIn>
  <button onClick={placeOrder}>Place order</button>
</SignedIn>