Apply when designing or modifying a BFF (Backend-for-Frontend) layer, middleware, or API proxy for a headless VTEX storefront. Covers BFF middleware architecture, public vs private API classification, VtexIdclientAutCookie management, API key protection, and secure request proxying. Use for any headless commerce project that must never expose VTEX_APP_KEY or call private VTEX APIs from the browser.
Apply when designing or modifying a BFF (Backend-for-Frontend) layer, middleware, or API proxy for a headless VTEX storefront. Covers BFF middleware architecture, public vs private API classification, VtexIdclientAutCookie management, API key protection, and secure request proxying. Use for any headless commerce project that must never expose VTEX_APP_KEY or call private VTEX APIs from the browser.
BFF Layer Design & Security
When this skill applies
Use this skill when building or modifying any headless VTEX storefront that communicates with VTEX APIs — whether a custom storefront, mobile app, or kiosk.
Setting up a BFF (Backend-for-Frontend) layer for a new headless project
Deciding which VTEX APIs need server-side proxying vs direct frontend calls
A BFF layer is mandatory for every headless VTEX project. There is no scenario where a headless storefront can safely operate without one.
Route all VTEX API calls through the BFF except Intelligent Search, which is the only API safe to call directly from the frontend.
Use VtexIdclientAutCookie (stored server-side) for shopper-scoped API calls. Use / for machine-to-machine calls.
X-VTEX-API-AppKey
X-VTEX-API-AppToken
Treat client-side exposure of VTEX_APP_KEY, VTEX_APP_TOKEN, VtexIdclientAutCookie, checkout cookies, or shopper/session tokens as a security violation — not as a recommendation or tradeoff. Use explicit wording such as “must not”, “never expose”, and “server-side only”, and avoid softer language such as “avoid”, “prefer”, or “ideally”.
Classify APIs by their path: /pub/ endpoints are public but most still need BFF proxying for session management; /pvt/ endpoints are private and must go through BFF.
Even public Checkout endpoints (/api/checkout/pub/) must be proxied through BFF for security — they handle sensitive personal data.
Create separate API keys with minimal permissions for different BFF modules rather than sharing one key with broad access.
Hard constraints
Constraint: A BFF layer is mandatory for headless VTEX — no exceptions
Every headless VTEX storefront MUST have a server-side BFF layer. Client-side code MUST NOT make direct HTTP requests to private VTEX API endpoints. All private API calls must be routed through the BFF.
Why this matters
Private VTEX APIs require X-VTEX-API-AppKey and X-VTEX-API-AppToken headers. If the frontend calls these APIs directly, the credentials must be embedded in client-side code or transmitted to the browser, exposing them to any user who opens browser DevTools. Stolen API keys can be used to access order data, modify pricing, or perform destructive administrative actions.
Detection
If you see fetch or axios calls to vtexcommercestable.com.br/api/checkout, /api/oms, /api/profile, or any /pvt/ endpoint in client-side code (files under src/, public/, app/, or any browser-executed bundle) → STOP immediately. These calls must be moved to the BFF.
Correct
// Frontend code — calls BFF, not VTEX directlyasyncfunctiongetOrderDetails(orderId: string): Promise<Order> {
const response = awaitfetch(`/api/bff/orders/${orderId}`, {
credentials: "include", // sends session cookie to BFF
});
if (!response.ok) {
thrownewError(`Failed to fetch order: ${response.status}`);
}
return response.json();
}
Constraint: VtexIdclientAutCookie MUST be managed server-side
The VtexIdclientAutCookie token MUST be stored in a secure server-side session (e.g., encrypted cookie, Redis session store) and MUST NOT be stored in localStorage, sessionStorage, or any client-accessible JavaScript variable.
Why this matters
The VtexIdclientAutCookie is a bearer token that authenticates all actions on behalf of a shopper — placing orders, viewing profile data, accessing payment information. If stored client-side, it can be stolen via XSS attacks, browser extensions, or shared/public computers. An attacker with this token can impersonate the shopper.
Detection
If you see VtexIdclientAutCookie referenced in localStorage.setItem, sessionStorage.setItem, or assigned to a JavaScript variable in client-side code → STOP immediately. The token must be managed exclusively server-side.
Correct
// BFF route — stores VtexIdclientAutCookie in server-side sessionimport { Router, Request, Response } from"express";
import session from"express-session";
const router = Router();
// After VTEX login callback, extract and store token server-side
router.get("/auth/callback", async (req: Request, res: Response) => {
const vtexAuthToken = req.cookies["VtexIdclientAutCookie"];
if (!vtexAuthToken) {
return res.status(401).json({ error: "Authentication failed" });
}
// Store in server-side session — never sent to frontend
req.session.vtexAuthToken = vtexAuthToken;
// Clear the cookie from the browser response
res.clearCookie("VtexIdclientAutCookie");
// Redirect to frontend with a secure session cookie
res.redirect("/account");
});
// BFF proxy uses session token for VTEX API calls
router.get("/api/bff/profile", async (req: Request, res: Response) => {
const vtexToken = req.session.vtexAuthToken;
if (!vtexToken) {
return res.status(401).json({ error: "Not authenticated" });
}
const response = awaitfetch(
`https://${process.env.VTEX_ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/profiles`,
{
headers: {
Cookie: `VtexIdclientAutCookie=${vtexToken}`,
},
}
);
const profile = await response.json();
res.json(profile);
});
Wrong
// Frontend code — stores auth token in localStorage (SECURITY VULNERABILITY)functionhandleLoginCallback() {
const params = newURLSearchParams(window.location.search);
const vtexToken = params.get("authToken");
// WRONG: token is now accessible to any JS on the page, including XSS payloadslocalStorage.setItem("VtexIdclientAutCookie", vtexToken!);
}
// Later, reads from localStorage and sends in headerasyncfunctiongetProfile() {
const token = localStorage.getItem("VtexIdclientAutCookie"); // EXPOSED!returnfetch("https://mystore.vtexcommercestable.com.br/api/checkout/pub/profiles", {
headers: { Cookie: `VtexIdclientAutCookie=${token}` },
});
}
Constraint: API keys MUST NOT appear in client-side code
VTEX_APP_KEY and VTEX_APP_TOKEN values MUST only exist in server-side environment variables and MUST NOT be present in any file that is bundled, served, or accessible to the browser.
Why this matters
API keys grant programmatic access to the VTEX platform with the permissions of their associated role. Exposing them in frontend bundles, public directories, or client-side environment variables (e.g., NEXT_PUBLIC_*, VITE_*) allows anyone to extract them and make unauthorized API calls.
Detection
If you see VTEX_APP_KEY, VTEX_APP_TOKEN, X-VTEX-API-AppKey, or X-VTEX-API-AppToken in files under src/, public/, app/ directories, or in environment variables prefixed with NEXT_PUBLIC_, VITE_, or REACT_APP_ → STOP immediately. Move these to server-side-only environment variables.
Architecture overview — how requests flow through the BFF:
Frontend (Browser/App)
│
├── Direct call (OK): Intelligent Search API (public, read-only)
│
└── All other requests → BFF Layer (Node.js/Express)
│
├── Injects VtexIdclientAutCookie from session
├── Injects X-VTEX-API-AppKey / X-VTEX-API-AppToken
├── Validates & sanitizes input
└── Proxies to VTEX APIs
│
├── Checkout API (/api/checkout/pub/...)
├── OMS API (/api/oms/pvt/...)
├── Profile API (/api/profile-system/pvt/...)
└── Other VTEX services
Minimal BFF server setup with session management:
// server/index.tsimport express from"express";
import session from"express-session";
import cookieParser from"cookie-parser";
import cors from"cors";
import { checkoutRoutes } from"./routes/checkout";
import { profileRoutes } from"./routes/profile";
import { ordersRoutes } from"./routes/orders";
const app = express();
app.use(express.json());
app.use(cookieParser());
app.use(
cors({
origin: process.env.FRONTEND_URL,
credentials: true,
})
);
app.use(
session({
// Production BFFs are typically multi-replica. Configure a shared session// store (e.g. connect-redis, connect-memcached, a Postgres-backed store)// here — the default MemoryStore is per-pod and silently drops values such// as orderFormId and vtexAuthToken when requests are routed to a different// replica. For ephemeral cross-step values that the browser already sees// (e.g. orderGroup between Step 1 and Step 3 of order placement), prefer// passing them through the request body instead of writing them to the// session — see headless-checkout-proxy.secret: process.env.SESSION_SECRET!,
resave: false,
saveUninitialized: false,
cookie: {
secure: process.env.NODE_ENV === "production",
httpOnly: true,
sameSite: "strict",
maxAge: 24 * 60 * 60 * 1000, // 24 hours (matches VtexIdclientAutCookie TTL)
},
})
);
// Mount BFF routes
app.use("/api/bff/checkout", checkoutRoutes);
app.use("/api/bff/profile", profileRoutes);
app.use("/api/bff/orders", ordersRoutes);
constPORT = process.env.PORT || 3001;
app.listen(PORT, () => {
console.log(`BFF server running on port ${PORT}`);
});
VTEX API client with credential injection for both auth types:
Proxying Intelligent Search through BFF: Routing every VTEX API call through the BFF, including Intelligent Search, adds unnecessary latency and server load. Intelligent Search is a public, read-only API designed for direct frontend consumption. Call it directly from the frontend.
// Frontend code — call Intelligent Search directly (this is correct!)asyncfunctionsearchProducts(query: string, from: number = 0, to: number = 19): Promise<SearchResult> {
const baseUrl = `https://${STORE_ACCOUNT}.vtexcommercestable.com.br`;
const response = awaitfetch(
`${baseUrl}/api/io/_v/api/intelligent-search/product_search/?query=${encodeURIComponent(query)}&from=${from}&to=${to}&locale=en-US`,
);
return response.json();
}
Sharing a single API key across all BFF operations: Using one API key with broad permissions (e.g., Owner role) for all BFF operations means a compromised key grants access to every VTEX resource. Create separate API keys for different BFF modules with minimal required permissions.
Logging API credentials or auth tokens: Logging request headers or full request objects during debugging inadvertently writes API keys or VtexIdclientAutCookie values to log files, which may be accessible to multiple team members or attackers. Sanitize all log output to strip sensitive headers before logging.
