Bring your own Mapbox token

Every TrailsIQ plan includes a monthly map-load allowance — the count of times a map widget mounts in a browser or the field app on your organization's behalf. Cross that cap and your maps switch to a solid green background (trails still render on top, no tiles fetched) until the trailing 30-day window rolls back below the limit.

If your org loads a lot of maps — public trail pages that get a lot of traffic, or a big active field-app fleet — the simplest way to get unlimited map loads is to bring your own Mapbox access token. You pay Mapbox directly on your own account and TrailsIQ stops counting your loads entirely.

Why bring your own token

• No TrailsIQ map-load cap. Once TrailsIQ resolves a Mapbox token on your organization, the plan cap stops applying — every map load your team, your visitors, and your public hub pages generate is billed to your Mapbox account instead of ours.
• Mapbox's own free tier is generous. As of 2026 Mapbox includes 50,000 map loads per month free before any billing kicks in — more than TrailsIQ's Core cap.
• Cheaper past that free tier. Above 50k Mapbox charges roughly $0.50 per 1,000 loads (check their current pricing). At the volumes that push you over TrailsIQ's Pro cap this is typically less than the plan upgrade.
• Same maps. Mapbox's Outdoors style is what our default renderer uses; when you supply a token we serve the same look and feel — nothing changes visually for your users.

What you need from Mapbox

1. A Mapbox account (free to create).
2. A public access token with the default scopes. Every Mapbox account gets one automatically; the token label is "Default public token" and it starts with pk.. If you'd rather create a purpose-built token, hit Create a token on your account page and leave every public scope checked (styles:read, fonts:read, datasets:read, vision:read — the defaults).
3. Optionally: set a spend cap on your Mapbox account so a viral public page can't run up an unexpected bill.

Do not use a secret token (starts with sk.). Secret tokens can create/delete Mapbox resources and are meant for server-side use; TrailsIQ stores the token client-side to reach Mapbox's tile servers, so a public pk. token is what you want.

Adding the token to TrailsIQ

1. Sign in to TrailsIQ as an owner or manager.
2. Open Settings (the top-level Settings page).
3. Scroll to the Branding section — the Mapbox access token (optional) field sits below the branding controls.
4. Paste your pk. token.
5. Hit Save settings.

The field's helper text will flip from "Leave blank to use the token TrailsIQ provides…" to a green "Using your own Mapbox account. Map tile requests hit your Mapbox token, not the platform's." — that's your confirmation the token is stored and active.

What changes after you save

• Immediately: every new page load your users open uses the Mapbox engine (mapbox-gl) with your token. Existing open pages continue on their cached settings until refresh.
• On the billing panel: the Map loads (30d) usage bar still fills up so you can see traffic patterns, but the plan cap check is skipped — you won't ever see the solid-green fallback and you won't get the 80%-of-plan email for map loads.
• Weather / condition / everything else: unchanged. This token only affects map rendering; every other TrailsIQ feature stays on the same plan quotas.
• Removing the token: clear the field, hit Save. TrailsIQ reverts to the platform-wide renderer and the plan cap comes back into effect immediately.

Common gotchas

• Public vs secret token. pk. = public (correct); sk. = secret (don't paste; it exposes account-write permissions if TrailsIQ is ever compromised).
• URL restrictions on the token. Mapbox lets you restrict a token to specific URLs. If you restrict yours, add every domain that will render a map: app.trailsiq.com, your public hub domain, localhost for dev if you preview from there. A token restricted to only your own domain will fail on app.trailsiq.com and leave the map blank.
• Spend caps are Mapbox-side. TrailsIQ has no way to enforce a monthly budget on your Mapbox account. Set one at account.mapbox.com if runaway public traffic worries you.
• Field-app builds shipped before your token existed still work — the token flows down on each app boot via the shared props, so the next foreground refresh picks it up.
• Revoking the token in Mapbox will surface as blank maps in TrailsIQ. Rotate carefully and paste the new one before deleting the old one.

What's next

• If you're on the fence about whether it's worth it, open Billing in TrailsIQ and check your Map loads (30d) usage. Under 20k a month → the platform cap is fine. Regularly over 40k → BYO Mapbox is almost certainly cheaper than an upgrade.
• Owners of high-traffic public hubs should also consider adding a spend cap on their Mapbox account so a link going viral can't produce a surprise bill.