Mapbox GL JS token rotation handling after deployment: cache inconsistency

Answer to the Core Question

Mapbox GL JS builds each tile URL by appending the current accessToken as a query parameter. Changing the token therefore changes the URL, so browsers treat the request as a new resource and bypass the HTTP cache for that request. However, tile responses are often served with a long Cache‑Control header (default 7 days). If a service worker is registered, it can cache those responses independently, and the old token can remain in the service‑worker cache until the worker is updated or the cache is purged. Mapbox GL JS itself offers no configuration to force a token refresh on each request; it simply relies on the browser’s caching layers.

How Major Browsers Treat the Caches

• HTTP Cache: The token is part of the URL, so a new token generates a new URL that is not served from the HTTP cache. A stale token is only served from HTTP cache when the same URL (same token) is requested and the response is still within its max‑age.
• Service Worker Cache: A PWA that registers a service worker can cache Mapbox tile responses. The service worker will continue to return the cached responses until the cache is explicitly cleared or the worker is re‑installed.
• Mapbox GL JS Internal Cache: The library keeps an in‑memory cache of recently used tiles. It will not automatically drop tiles when the token changes; a style or map reload is required to flush it.

Confirmed Facts

• Changing the token changes the tile URL, so HTTP cache is bypassed for that request.
• Mapbox tile responses normally include Cache‑Control: max‑age=604800 (7 days).
• Service workers can retain old tile responses until the cache is cleared.
• Mapbox GL JS does not expose a setting to refresh the token on every tile request.

Practical Steps to Invalidate Tiles After Token Rotation

1. Update the token in your app. Set mapboxgl.accessToken = NEW_TOKEN; before creating or reloading the map.
2. Force a style reload. Call map.setStyle(STYLE_URL);. This clears Mapbox GL JS’s internal tile cache and forces new tile requests.
3. Add a cache‑busting query parameter. Append a unique value to the style URL, e.g. STYLE_URL + '?v=' + Date.now(). This guarantees a new URL that bypasses both HTTP and service‑worker caches for that request.
4. Clear the service‑worker cache (if used). In your service‑worker script, expose a message handler that deletes the tile cache:

   self.addEventListener('message', event => {
     if (event.data && event.data.type === 'clear-mapbox-cache') {
       caches.delete('mapbox-tiles').then(() => console.log('Mapbox cache cleared'));
     }
   });
   

   Then trigger it from the page after updating the token:

   navigator.serviceWorker.controller.postMessage({type: 'clear-mapbox-cache'});
   

5. Verify the result. Open DevTools → Network. Ensure that tile requests contain the new token and that the From cache column shows Network or Service Worker is not used. A 401 should no longer appear.

Optional: Use Workbox or Custom Service Worker Logic

If you use Workbox, you can set expiration: {maxAgeSeconds: 0} for Mapbox tiles during token rotation, forcing a network fetch on the next request.

Missing Diagnostic Detail

Does your application register a service worker? If so, the service‑worker cache must be cleared after the token change; otherwise the old token may still be served until the cache expires.

Bottom Line

Token rotation is safe as long as you (1) reload the style, (2) add a cache‑busting query string, and (3) clear any service‑worker tile cache. Mapbox GL JS itself cannot force a token refresh; the browser’s caching layers and your own cache‑busting strategy are the only reliable controls.