BeNomad Tiles

Sessions & tokens#

One HTTP Basic login against the tiles worker returns a JWT valid ~1 hour, and every tile, style, glyph and discovery request must carry it, by cookie, header or query parameter.

At a glance#

• Login: POST {tilesBase}/api/login with Authorization: Basic base64(login:password) → { ok, username, token }, plus an HttpOnly session cookie.
• Token lifetime ~1 hour. Limits: 100 req/s per user, Range ≤ 10 MB, HTTPS only.
• Four wire modes on tilesAuth: auto (default), cookie, header, query.
• auto resolves once, at construction: same registrable domain as tilesHost ⇒ cookie; cross-site ⇒ X-Session-Token header.
• Renewal is automatic: proactive 5 minutes before the exp claim, reactive on 401, plus visibilitychange and offline handling.
• The token is persisted per ctx.tokenStorage: 'session' (default), 'local' or 'memory', under the key bemap_tiles_token.
• Credential-less integrations: a backend token provider, or the v2.0.2 proxy option.

Usage#

The supported path: set tilesHost and let the SDK own the session:

var ctx = new bemap.Context({
    login:     'YOUR_LOGIN',
    password:  'YOUR_PASSWORD',
    secure:    true,
    host:      'bemap.benomad.com',
    tilesHost: 'mptiles-api.benomad.net'
});

var map = new bemap.MapLibreMap(ctx, 'map');
map.isTokenValid();   // Boolean      map.getToken();  // String | null
map.refreshToken();   // Promise<String>

Pin the wire mode only when auto cannot be right for your deployment, for example a native WebView that cannot inject headers:

new bemap.Context({ tilesHost: 'mptiles-api.benomad.net', tilesAuth: 'query' });   // shorthand
new bemap.Context({ tilesHost: '…', tilesAuth: { mode: 'header', tokenHeader: 'X-Session-Token' } });
new bemap.MapLibreMap(ctx, 'map', { tilesAuth: { mode: 'cookie' } });              // per-map override

Raw HTTP: log in, then spend the token. Never inline the credentials:

TOKEN=$(curl -s -X POST "https://mptiles-api.benomad.net/api/login" \
  -u "$LOGIN:$PASS" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

# 200 while the session is valid, 401 once it has expired
curl -s -o /dev/null -w '%{http_code}\n' -H "X-Session-Token: $TOKEN" \
  "https://mptiles-api.benomad.net/api/status"

# a z/x/y MVT tile with the same token
curl -s -H "X-Session-Token: $TOKEN" \
  "https://mptiles-api.benomad.net/default/12/2074/1409.pbf" --output tile.pbf

Reference#

Session endpoints#

{tilesBase} is https://<tilesHost>: ctx.getTilesBaseUrl(), plus getTilesLoginUrl() / getTilesStatusUrl() / getTilesLogoutUrl().

Limits#

Wire modes: tilesAuth#

Set on the Context, overridable field-by-field per map. Accepts the string shorthand ('auto', 'cookie', 'header', 'query') or the full object. An unrecognised mode falls back to auto.

The resolved mode applies uniformly to the pmtiles Range fetch interceptor, MapLibre's transformRequest (style, glyphs, sprites, z/x/y), bemap.TilesStyle.fetch, and to login / logout.

bemap.TilesAuth(ctx, options)#

Constructed for you by bemap.MapLibreMap. Instantiate it directly only in a raw-MapLibre integration.

Token storage: ctx.tokenStorage#

Key bemap_tiles_token, value { token, exp }. Storage failures (private mode, quota, disabled) degrade silently to memory-only.

Error codes#

Raised through options.onError when you construct bemap.TilesAuth yourself. The map creates its own instance internally and routes those errors to an internal channel that 2.0.2 exposes no public subscription for: in practice you observe them in the console. See Map errors.

Notes#

Renewal timeline. After every successful login the SDK parses the JWT exp claim and schedules a refresh at exp − 5 minutes (clamped to [0, 24 h]); when exp cannot be parsed it falls back to a fixed 55 minutes. A 401 on a tile or style triggers handle401(): refresh, then a setStyle() reload so pending requests retry with the new token. On document.visibilitychange to visible the SDK re-logs in if the token has already expired, refreshes if it expires within 5 minutes, and does nothing otherwise. When navigator.onLine is false the renewal is queued and replayed on the next online event.

Credential-less: backend token provider. Your server holds the credentials, exposes one authenticated endpoint that forwards POST /api/login with the Basic header, and returns the JSON body unchanged; the browser receives only the short-lived JWT and fetches tiles directly from BeNomad. Only the tiles credentials move server-side, see The Context.

Credential-less: proxy (v2.0.2). new bemap.Context({ proxy: 'your-proxy.example.com', tilesHost: '…' }) routes the REST/WMS calls and the tiles login through your server, which injects the credentials; no Authorization ever leaves the browser. Tile bytes still go direct to tilesHost. Because the login response then comes from the proxy origin, the session cookie could never be sent to tilesHost, so the SDK forces the header wire, overriding an explicit tilesAuth: 'cookie' with a one-shot console warning ('query' is honoured). See The Context.

Gotchas#

• tokenStorage values are 'session' / 'local' / 'memory', not 'sessionStorage' / 'localStorage'. An unrecognised value silently falls back to sessionStorage.
• Never patch window.fetch yourself to inject the token. The SDK already owns a scoped, host-checked wrapper; a second patch double-stamps requests or drops the Range policy.
• Pinning tilesAuth: 'cookie' on a cross-site app will 401 in Safari, Firefox and Chrome incognito. That is precisely what auto exists to avoid: leave it unset.
• getHistory() is diagnostic only. It deliberately keeps just the exp claim, so logging it cannot exfiltrate a still-valid token. Never log getToken().
• A missing login / password produces a one-shot console warning, then UNAUTHORIZED, not a silent blank map. Check the console before debugging CORS.
• isValid() returns true when exp is unparseable. A non-JWT token is assumed good until the server answers 401; the fixed 55-minute renewal covers the rest.
• logout() without { serverSide: true } only clears the client. The session stays valid on the worker until it expires.
• A 403 on a .pmtiles request is usually not auth. No Range header, a Range over 10 MB, or a multi-part Range are all rejected with 403, see Troubleshooting.

See also#

• Overview & access: the access contract in context, environments, integration paths
• Web: PMTiles: where the token is attached on the browser path
• Mobile & fleet z/x/y: the ?token= query wire for native clients
• Cache & slices: why the wire mode changes the preflight and cache behaviour
• Troubleshooting: 401 / 403 / CORS symptom to fix
• The Context: tilesHost, tilesAuth, tokenStorage, proxy
• Error handling: the typed-rejection pattern
• Error codes: every bemap.Error constant