Skip to main content

API Proxy

The API Proxy feature lets you route API calls through the Widget Builder server instead of making them directly from the user's browser. This keeps sensitive data like API keys, authentication tokens, and endpoint URLs hidden from end users.

Why Use the API Proxy?​

When a widget makes an API request directly from the browser, everything is visible in the browser's network inspector: the URL, headers, request body, and any tokens or API keys included. Anyone with developer tools open can see this data.

With the API proxy enabled, the request flow changes:

Browser  -->  Widget Builder Server  -->  External API
Browser  <--  Widget Builder Server  <--  External API

The browser only sees a request to the Widget Builder server. The actual external API URL, headers (including authentication tokens), and request body details are never exposed to the client.

Key Benefits​

  • Hidden credentials -- API keys, bearer tokens, and authentication headers stay on the server
  • Hidden endpoints -- The actual API URL is not visible in the browser
  • No CORS issues -- Since the request comes from the server, browser CORS restrictions do not apply
  • Server-side Handlebars -- Handlebars helpers like {{staffbaseIdToken}} and {{staffbaseAccessToken}} are resolved on the server, so token values are never sent to the browser

How to Enable It​

In the API request form (either in the standalone API section or in a widget's API panel), toggle "Route using Widget Builder" to the on position.

That is all you need to do. When the toggle is enabled, the Widget Builder automatically rewrites the request so it is routed through the server at runtime.

What Gets Hidden​

When proxy mode is active, the following are never visible to the end user's browser:

Hidden from browserExample
API endpoint URLhttps://api.example.com/v2/data
Request headersAuthorization: Bearer sk-secret-key-123
Authentication tokens{{staffbaseIdToken}}, {{staffbaseAccessToken}}
Integration tokens{{microsoftAccessToken}}, {{googleAccessToken}}, etc.
Request body contentAny sensitive data in POST/PUT request bodies

The browser only sees a POST request to the Widget Builder's own /api/proxy/... endpoint.

How It Works Internally​

When proxy is enabled on an API request, the Widget Builder transforms the widget's API configuration at serve time:

  1. The original URL, method, headers, and body are stored in the database but not sent to the browser
  2. Instead, the widget receives a rewritten request pointing to the Widget Builder's proxy endpoint
  3. At runtime, the widget sends a POST request to the Widget Builder server
  4. The server looks up the original API configuration, resolves any Handlebars templates (including authentication tokens), and makes the actual request to the external API
  5. The response is forwarded back to the browser

Handlebars in Proxy Mode​

Handlebars helpers work on the server side when proxy is enabled. This is especially important for authentication helpers:

  • {{staffbaseIdToken}} -- Resolved from the user's authenticated session on the server
  • {{staffbaseAccessToken}} -- Resolved from the access token header on the server
  • {{microsoftAccessToken}}, {{googleAccessToken}}, {{boxAccessToken}}, {{atlassianAccessToken}}, {{serviceNowAccessToken}} -- Integration tokens resolved on the server

Since these are resolved server-side, the actual token values never appear in the browser's network traffic.

All other Handlebars helpers (like {{json ...}}, {{encode ...}}, {{formatDate ...}}) also work in proxy mode, as the full Handlebars engine runs on the server before making the outbound request.

Limitations​

  • Rate limiting -- Proxy requests are rate-limited (300 requests per 60-second window per client by default). This protects against abuse but may affect high-traffic widgets
  • Redirect handling -- The proxy follows up to 5 redirects automatically. Redirect responses (3xx) are wrapped and returned as 200 responses with redirect metadata to prevent the browser from following them
  • Response forwarding -- Only specific response headers are forwarded back to the browser: Content-Type, Content-Disposition, Content-Length, rate limit headers, and Location
  • Proxy-only requests -- The proxy only works for API requests defined within the Widget Builder. You cannot use it for arbitrary external calls from custom JavaScript

When to Use the Proxy​

Use the proxy when:

  • Your API request includes API keys, secrets, or authentication tokens in headers or body
  • You want to hide the actual API endpoint URL from end users
  • The external API does not support CORS and cannot be called directly from the browser
  • You are using Staffbase or third-party integration tokens that should not be exposed

Direct requests are fine when:

  • The API is public and requires no authentication
  • CORS is properly configured for your domain
  • There is no sensitive data in the request