skills.rest
exilonX
exilonXCOMMUNITY
Explore all skills by this author →
GitHub

headless-bff-architecture

Design hardened BFF proxies for headless VTEX storefronts to protect credentials.

Updated Mar 27, 2026
Search Tags:#bff#headless vtex#api key security#session auth#server-side token storage#api proxying#vtex private apis
One-click install
npx skills add https://github.com/exilonX/ap2 --skill headless-bff-architecture-exilonx
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: headless-bff-architecture
Source: https://github.com/exilonX/ap2/tree/main/.agents/skills/headless-bff-architecture
Command: npx skills add https://github.com/exilonX/ap2 --skill headless-bff-architecture-exilonx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps prevent account takeover and credential leakage by enforcing a secure Backend-for-Frontend (BFF) architecture for headless VTEX storefronts, ensuring private VTEX APIs are never called directly from the browser.

Core Features & Use Cases

  • BFF request proxying with credential injection: Routes all non-Intelligent Search VTEX API calls through the BFF while injecting server-side secrets in a controlled way.
  • Strict session and token handling: Ensures VtexIdclientAutCookie is stored server-side (session-based) and never placed in localStorage, sessionStorage, or client-exposed variables.
  • API key protection and segmentation: Enforces that VTEX_APP_KEY and VTEX_APP_TOKEN exist only in server-side environment variables, and recommends splitting keys by BFF module with least permissions.
  • Public vs private endpoint classification: Uses /pvt/ as a hard rule for BFF-only access and clarifies when /pub/ endpoints still require proxying for session safety.

Use case: You’re building a headless VTEX storefront (custom storefront, mobile app, or kiosk) where the frontend must never expose VTEX_APP_KEY / VTEX_APP_TOKEN and must not call private VTEX APIs directly; this Skill provides decision rules and a review checklist to harden the design.

Quick Start

Use the headless-bff-architecture skill to review your current headless VTEX setup and produce a secure BFF proxy plan that keeps VTEX secrets and shopper tokens server-side only.

Frequently Asked Questions about headless-bff-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I secure VTEX API keys in a headless storefront architecture?▼

To secure VTEX API keys in a headless storefront, store VTEX_APP_KEY and VTEX_APP_TOKEN exclusively in server-side environment variables and route all API calls through a Backend-for-Frontend (BFF) proxy to inject credentials securely.

Where should the VtexIdclientAutCookie be stored in a headless VTEX BFF setup?▼

The VtexIdclientAutCookie must be stored in server-side sessions within your BFF architecture. It should never be placed in browser localStorage, sessionStorage, or client-exposed variables to prevent session hijacking.

What is the difference between public and private VTEX endpoints for BFF proxying?▼

Private VTEX endpoints containing /pvt/ require strict BFF-only access with credential injection. Public endpoints (/pub/) may still require BFF proxying for session safety and to prevent direct browser exposure of shopper tokens.

Does VTEX Intelligent Search require routing through a BFF proxy?▼

VTEX Intelligent Search API calls do not require routing through the BFF proxy. You can call Intelligent Search directly from the browser, but all other VTEX APIs must route through the BFF for credential protection.

How do I prevent account takeover in headless VTEX commerce implementations?▼

Prevent account takeover in headless VTEX commerce by implementing a hardened BFF that proxies private APIs, manages shopper sessions server-side, and strictly separates public endpoints from private ones requiring credential injection.

Can I use VTEX_APP_KEY directly in my frontend JavaScript for API calls?▼

No, VTEX_APP_KEY and VTEX_APP_TOKEN must never be used directly in frontend JavaScript. They should exist only in server-side environment variables with least permissions split by BFF module to prevent credential leakage.

Related Skills

Explore More Software Engineering Skills→
vtexvtex
39

headless-bff-architecture

Propose a secure BFF architecture routing VTEX API calls with server-side cookie management.

Official
Advanced
vtexdocsvtexdocs
39

headless-bff-architecture

Route private VTEX API calls through a secure Express-based BFF.

Official
Advanced
vtexdocsvtexdocs
39

headless-checkout-proxy

Proxy VTEX Checkout API calls through a BFF with server-side session and cookie management.

Official
Advanced
exilonXexilonX

vtex-io-service-apps

Build VTEX IO service routes using @vtex/api clients via ctx.clients.

Community
Advanced