headless-bff-architecture

To securely proxy VTEX private APIs, route frontend calls through a server-side BFF that validates requests and manages authentication. This backend layer protects VTEX AppKeys and shopper tokens from frontend exposure.

A BFF layer is mandatory for headless VTEX apps to prevent exposing API keys and shopper credentials in frontend code. It centralizes credential management and applies security guardrails like input validation and server-side session management.

Handle VtexIdclientAutCookie and API keys server-side by configuring VTEX credentials via environment variables in an Express-based BFF. This protects shopper sessions and machine credentials while routing private VTEX endpoints.

Public VTEX endpoints can be accessed directly, while private endpoints must route through the BFF with validation and security guardrails. The BFF applies routing rules to protect credentials and manage per-module API key separation.

An Express-based BFF is the recommended implementation for VTEX headless projects. You install a minimal Express server, configure server-side VTEX credentials via environment variables, and route private endpoints through it.

The BFF approach requires server-side infrastructure and careful credential management via environment variables. Limitations include the need for per-module API key separation and maintaining validation guardrails for all private endpoint routing.