Architecture Note: Proxying Mapbox Vector Tiles to Protect Tokens and Control Caching

Embedding Mapbox vector tiles directly in a browser exposes long-lived access tokens in network requests, even when those tokens are restricted by URL. Teams that need to hide credentials, enforce per-user authorization, or control upstream request volume cannot rely on client-side tokens alone. The smallest suitable design is a stateless backend proxy that authenticates the application user, attaches a server-side Mapbox token, forwards the tile request, and caches the response at the edge.

Requirements

The proxy must satisfy four constraints:

1. No Mapbox secrets in the client tier. Browser tokens are visible in developer tools and network logs; they are identifiers, not true secrets.
2. Application authorization before forwarding. The proxy, not Mapbox, decides whether a given user may request a tile.
3. Cache control. Repeated requests for the same tile should not hit Mapbox every time, reducing cost and latency.
4. Observability. Operators need visibility into proxy errors, upstream throttling, cache effectiveness, and token validity.

Smallest Suitable Design

A stateless HTTP proxy placed between the client and Mapbox meets these requirements without introducing session affinity or complex state. The flow is straightforward: the client requests a tile from the proxy, the proxy validates the application session, appends the Mapbox access token from a server-side secret store, forwards the request to the Mapbox tile endpoint, and returns the response with appropriate cache headers.

The following nginx snippet illustrates the pattern. It is an example only; endpoint paths and token header names must be verified against current Mapbox documentation before deployment.

# Run on the backend proxy host; requires nginx with proxy_cache enabled
# and a server-side environment variable holding the Mapbox token.

location /tiles/ {
    # 1. Application authorization: reject unauthenticated requests
    #    before any upstream call is made.
    auth_request /auth;

    # 2. Attach the Mapbox token server-side. The client never sees it.
    proxy_set_header Authorization "Bearer $MAPBOX_SERVER_TOKEN";

    # 3. Forward to Mapbox. Replace the upstream URL with the current
    #    vector tile endpoint documented by Mapbox.
    proxy_pass https://api.mapbox.com/;

    # 4. Cache tile responses at the proxy layer.
    proxy_cache tiles;
    proxy_cache_valid 200 24h;
    proxy_cache_use_stale error timeout updating;
}

Placeholders such as $MAPBOX_SERVER_TOKEN and /auth must be replaced with your actual secret injection and authentication endpoint. Expected checks after configuration include confirming that the proxy returns tile data to authenticated clients and that unauthenticated requests receive a 401 or 403 before reaching Mapbox.

Trust and Data Boundaries

The architecture creates three distinct trust zones:

Tier	Trust level	Holds Mapbox token?	Responsibility
Client (browser/mobile)	Untrusted	No	Requests tiles via the proxy; holds only an application session credential.
Backend proxy	Trusted	Yes	Enforces application authorization, injects the Mapbox token, manages caching.
Mapbox upstream	External service	N/A	Serves vector tiles and styles; sees only the proxy's requests.

Data crosses these boundaries in one direction: client to proxy, proxy to Mapbox. No Mapbox credential should ever appear in a client-side request, response, or local storage.

Operational Checks

Monitoring should focus on signals that indicate the proxy is protecting credentials without becoming a silent bottleneck:

• Proxy error rate. Spikes in 5xx responses from the proxy itself indicate bugs or resource exhaustion.
• Upstream throttling. Mapbox may return rate-limit responses (commonly HTTP 429) if the proxy forwards too much traffic. Track these separately from proxy errors.
• Cache hit ratio. A low hit ratio suggests the cache key is too specific or the TTL is too short, increasing upstream load.
• Token validity. Authentication failures from Mapbox (commonly HTTP 401) mean the server-side token is expired, revoked, or lacks the required scopes.
• Authorization failures. A sudden rise in 401/403 responses from the proxy may indicate session bugs or abuse.

To verify that no token leaks to the client, open browser developer tools, load a map page, and inspect the network tab. Tile requests should target your proxy domain, and neither the request URL nor response headers should contain a Mapbox access token. You can also run the following command from a developer machine to confirm the proxy rejects unauthenticated requests:

# Run from any machine that can reach the proxy; no special permissions required.
# Replace PROXY_HOST and TILE_PATH with your actual values.
curl -i https://PROXY_HOST/tiles/TILE_PATH

# Expected check: response status is 401 or 403.
# Risk: if the proxy returns tile data, authorization is not enforced.

Failure Modes

Introducing a proxy adds a new availability dependency. If the proxy is down, the map is down. Size the proxy tier for peak concurrent tile requests, and consider a fallback or degraded mode if maps are mission-critical.

Cache stampedes can occur after a style or data update when many cached entries expire simultaneously and clients request fresh tiles in a burst. Mitigate by staggering TTLs or using a request-coalescing mechanism at the proxy.

Stale tiles are a related risk: if Mapbox updates underlying vector data or style schemas, the proxy may continue serving cached responses until the TTL expires. Invalidate the cache explicitly when you deploy style changes.

Finally, some Mapbox client-side features—such as usage telemetry or map feedback—may not function correctly when tile requests are intercepted by a proxy. Test these features explicitly rather than assuming they will pass through.

Conditions That Change the Design

The proxy is not always necessary. If traffic is low and you use only public styles, direct client-side tokens with URL restrictions may be acceptable, accepting the trade-off that those tokens are visible in browser requests. If strict data-residency or compliance requirements apply, self-hosted tiles or Mapbox Atlas may be required instead of a proxy in front of Mapbox's cloud service.

If you later need real-time collaboration or sub-second updates, the caching TTLs and invalidation strategy will need revisiting, but the trust boundary—client without secrets, proxy with secrets—remains the same.

Limitations and Verification

This design does not make browser tokens secret; it removes them from the client entirely. It also does not eliminate upstream dependency: Mapbox availability still affects your maps. Vector tile payloads and style specifications can change between Mapbox versions, so cached entries must be invalidated when styles or tile schemas are updated.

Before production, verify current Mapbox documentation for token scope options and API endpoint formats to ensure the proxy targets the correct URLs. Load test the proxy with concurrent tile requests to measure cache hit ratios and confirm that upstream request volume stays within expected bounds. Induce upstream authentication errors and rate-limit responses to verify that the proxy fails safely and does not leak internal error details to clients.