Add support for custom HTTP headers in tile requests

[loaiz1982]

Feature Description

Use Case:
I'm serving PMTiles with TOTP-based authentication for security. Currently, I'm passing the token as a URL query parameter (?token=123456), but this
is suboptimal because:

1. Security: Tokens appear in logs, browser history, and cache keys
2. Caching: Each token rotation creates new cache entries, reducing cache efficiency
3. Best Practice: Authentication tokens should be sent via headers (e.g., Authorization or X-Map-Token)

Requested Feature:
Add support for custom HTTP headers when fetching tiles from tile sources (PMTiles, raster, vector). This would allow:

  MapLibreMap(
    styleString: styleJson,
    tileRequestHeaders: {
      'X-Map-Token': totpToken,
      'Authorization': 'Bearer $token',
    },
  )

Benefits:

• Tokens excluded from URLs (better security, cleaner logs)
• Improved cache efficiency (cache key based on URL, not token)
• Follows HTTP authentication best practices
• Enables proper CDN caching with authenticated tiles

Current Workaround:
Using query parameters (/tiles.pmtiles?token=123456), which works but has the limitations mentioned above.

Sample Use Case

  MapLibreMap(
    styleString: styleJson,
    tileRequestHeaders: {
      'X-Map-Token': totpToken,
      'Authorization': 'Bearer $token',
    },
  )

Existing Alternatives or Workarounds

Using query parameters (/tiles.pmtiles?token=123456), which works but has the limitations mentioned above.

Additional Context

No response

[josxha]

It should be possible to add custom headers for example by using a custom OkHttpClient on android with setOkHttpClient.

For iOS I think it's a bit more tricky. There is an open issue in maplibre-native that mentions some workarounds: maplibre/maplibre-native#126

Feel free do dive into it and contribute if you want. 😄

[loaiz1982]

Thank you for the quick response @josxha!

I appreciate you pointing me to the platform-specific workarounds. However, after reviewing the suggestions:

1. Android: Using a custom OkHttpClient with setOkHttpClient
2. iOS: The maplibre-native issue fix: broken scalebar on web #126

I realize this requires deep platform-specific knowledge that I don't currently have. Since implementing this would involve native Android/iOS code and the iOS solution is described as "tricky," I think it's beyond my current expertise to contribute effectively.

Thanks again for maintaining this excellent library!
I will wait for upstream progress on maplibre-native issue #126

[josxha]

No worries. There are currently tasks with an higher prio for me but I might have a look at it at some point if more time.