sfnext-authentication

Implement authentication in Storefront Next using split-cookie architecture, SLAS tokens, and auth middleware. Use when accessing user identity in loaders, detecting guest vs registered users, using getAuth or useAuth, or understanding session management and token refresh.

View SKILL.md on GitHub → Source repository Provider profile

Provider: Salesforce Commerce Cloud Path in repo: skills/storefront-next/skills/sfnext-authentication/SKILL.md

Skill body

Authentication Skill

This skill covers Storefront Next’s split-cookie authentication architecture with SLAS (Shopper Login and API Access Service).

Overview

Storefront Next uses a split-cookie architecture separating server and client auth concerns:

Server middleware (auth.server.ts) — Manages SLAS tokens, writes cookies, handles token refresh
React Context (AuthProvider) — Provides public session data (non-sensitive fields) to components via useAuth()

Cookie	Purpose	User Type	Expiry	HttpOnly
`cc-nx-g`	Guest refresh token	Guest	30 days	No
`cc-nx`	Registered refresh token	Registered	90 days	No
`cc-at`	Access token	Both	30 min	No
`usid`	User session ID	Both	Matches refresh	No
`customerId`	Customer ID	Registered	Matches refresh	No

Key points:

Only ONE refresh token exists at a time (guest OR registered, never both)
User type is derived from which refresh token is present
Cookies are auto-namespaced with siteId
Tokens auto-refresh when expired

Usage in Loaders/Actions

import { getAuth } from '@/middlewares/auth.server';

export function loader({ context }: LoaderFunctionArgs) {
    const auth = getAuth(context);

    const { accessToken, customerId, userType } = auth;
    const isGuest = userType === 'guest';
    const isRegistered = userType === 'registered';

    return { isGuest, customerId };
}

Usage in Components

import { useAuth } from '@/providers/auth';

export function MyComponent() {
    const auth = useAuth();

    if (auth?.userType === 'guest') {
        return <LoginPrompt />;
    }

    return <div>Welcome, customer {auth?.customerId}</div>;
}

Common Patterns

Protected Routes

export function loader({ context }: LoaderFunctionArgs) {
    const auth = getAuth(context);

    if (auth.userType === 'guest') {
        throw redirect('/login');
    }

    const clients = createApiClients(context);
    return {
        orders: clients.shopperOrders.getOrders({
            params: { path: { customerId: auth.customerId } }
        }).then(({ data }) => data),
    };
}

Conditional Data Loading

export function loader({ context }: LoaderFunctionArgs) {
    const auth = getAuth(context);
    const clients = createApiClients(context);

    const base = {
        products: clients.shopperProducts.getProducts({...}).then(({ data }) => data),
    };

    if (auth.userType === 'registered') {
        return {
            ...base,
            wishlist: clients.shopperCustomers.getWishlist({...}).then(({ data }) => data),
        };
    }

    return base;
}

Troubleshooting

Issue	Cause	Solution
`auth` is undefined	Missing auth middleware	Ensure `auth.server.ts` middleware is configured
Always guest	Refresh token expired	Check cookie expiry; SLAS auto-refreshes
Token errors in SCAPI	Stale access token	Tokens auto-refresh; check SLAS client configuration

storefront-next:sfnext-data-fetching - Using auth context in loader functions
storefront-next:sfnext-configuration - SLAS client configuration
storefront-next:sfnext-hybrid-storefronts - Session bridging with SFRA