Skip to main content
Version: next

Debug endpoint

The /__front-commerce/debug URL provides comprehensive debugging information about the application's configuration, user session, and request context.

warning

This endpoint exposes sensitive system information (configuration values, user sessions, request headers). It is protected by security measures and should never be accessible in production environments.

Overview​

The debug endpoint is a developer tool that helps you inspect the current state of your Front-Commerce application, including:

  • Environment configuration
  • User session data
  • Shop configuration
  • Request details and headers

Access control​

The debug endpoint has multiple security layers:

EnvironmentAccess
Production (FRONT_COMMERCE_ENV=production)Blocked - returns 404
Development (NODE_ENV=development)Open - no token required
Staging/Preview (NODE_ENV=production, non-prod FC env)Token required via ?token= query parameter

Token authentication​

In staging or preview environments (where NODE_ENV=production but FRONT_COMMERCE_ENV is not production), you must provide a valid token:

/__front-commerce/debug?token=YOUR_SECRET_TOKEN

The token must match the value of the FRONT_COMMERCE_DEBUG_TOKEN environment variable. Invalid or missing tokens return a 404 response (to avoid revealing the endpoint exists).

API Reference​

/__front-commerce/debug​

Returns a JSON object containing comprehensive debugging information.

Response structure​

{
  "env": "development",
  "user": {
    "clientIp": "127.0.0.1",
    "session": { ... },
    "contributionMode": { ... },
    "journey": { ... },
    "isAnonymous": true
  },
  "config": {
    "account": { ... },
    "allShops": { ... },
    "cors": { ... },
    "currentShopId": "default",
    "debugToken": "...",
    "isShopFallback": false,
    "maintenanceMode": { ... },
    "shop": { ... },
    "public": { ... },
    "cache": { ... },
    "contentSecurityPolicy": { ... },
    "device": { ... }
  },
  "request": {
    "url": "http://localhost:4000/__front-commerce/debug",
    "referrer": null,
    "method": "GET",
    "headers": { ... }
  }
}

Response fields​

FieldDescription
envCurrent application environment (development or production)
userUser-related data including session, contribution mode, journey
configFull configuration object from all registered providers
requestRequest details including URL, method, referrer, and headers

Query parameter: token​

Required in staging/preview environments. The token value must match the FRONT_COMMERCE_DEBUG_TOKEN environment variable.

/__front-commerce/debug?token=your-secret-token

Configuration​

The debug endpoint is configured via the FRONT_COMMERCE_DEBUG_TOKEN environment variable:

# .env
FRONT_COMMERCE_DEBUG_TOKEN=your-secure-random-token
tip

Generate a secure random token using:

openssl rand -hex 32

Usage examples​

Local development​

In development mode, access the endpoint directly:

http://localhost:4000/__front-commerce/debug

Staging environment​

In staging environments with token protection:

https://staging.example.com/__front-commerce/debug?token=your-token

Debugging configuration​

The endpoint is useful for verifying:

  • Configuration providers are correctly registered
  • Environment variables are properly loaded
  • Shop configuration matches expectations
  • Cache strategies are correctly configured
  • Content Security Policy directives