В экосистеме Mapbox GL JS доступ к данным и стилям карты строится вокруг использования публичного или секретного access token, выдаваемого платформой Mapbox. Одним из ключевых механизмов защиты является ограничение использования токена по доменам (Allowed URLs / Allowed domains).
Эта система предотвращает несанкционированное использование токена на сторонних сайтах и позволяет привязать ключ API к конкретным веб-приложениям.
При каждом запросе Mapbox GL JS отправляет HTTP-запросы к API Mapbox, включая:
В запрос автоматически добавляется access token. Сервер Mapbox проверяет:
Origin / Referer)Если домен отсутствует в списке разрешённых — запрос отклоняется.
Самый строгий вариант — привязка токена к конкретному домену:
example.comapp.example.comВ этом случае запросы с других поддоменов будут отклонены.
Некоторые конфигурации допускают использование поддоменов:
*.example.comЭто позволяет использовать один токен для:
app.example.comadmin.example.commap.example.comНо не распространяется на:
example.orgevil-example.comДополнительно учитывается протокол:
https://example.comhttp://localhost:3000Особенно важно для разработки, так как локальные окружения часто требуют отдельного разрешения.
При разработке часто используются адреса:
localhost127.0.0.10.0.0.0Для корректной работы Mapbox GL JS необходимо явно добавить эти адреса в список разрешённых доменов токена.
Типичные варианты:
http://localhost:3000http://127.0.0.1:5173Без этого браузерные запросы будут завершаться ошибкой авторизации.
Mapbox GL JS не ограничивает домены самостоятельно. Проверка происходит на уровне:
Referer, Origin)Таким образом, библиотека выступает только как транспортный слой, а контроль безопасности реализуется на стороне API Mapbox.
Возникает при:
Типичный ответ API:
401 UnauthorizedNot Authorized - No TokenПоявляется, если:
Хотя Mapbox использует собственные домены API, браузер может блокировать запросы при:
access-control-allow-originВ панели управления токенами задаётся список Allowed URLs:
example.com)app.example.com)localhost:3000)Изменения вступают в силу практически мгновенно и применяются ко всем новым запросам.
Используется несколько токенов:
Рекомендуется:
* в productionПример стратегии:
https://app.example.com → production tokenhttps://staging.example.com → staging tokenhttp://localhost:5173 → dev tokenЭто снижает риск утечки ключа и его использования вне контекста приложения.
В одностраничных приложениях (SPA) важно учитывать:
Однако переход на внешний домен через редирект приводит к блокировке запросов.
При встраивании карты в iframe возникают дополнительные ограничения:
SameSite
политикиПри использовании CDN или reverse proxy:
wwwhttps версия доменаПри обработке запроса сервер Mapbox выполняет:
Нарушение любого из первых двух этапов приводит к мгновенному отказу без выполнения операций.
Даже при наличии ограничений по доменам важно учитывать:
Поэтому доменные ограничения рассматриваются как слой защиты от случайного или массового злоупотребления, а не как полноценная система аутентификации.
Система разрешённых доменов в Mapbox GL JS формирует базовый уровень контроля доступа:
В связке с архитектурой Mapbox GL JS и инфраструктурой Mapbox этот механизм обеспечивает предсказуемое и ограниченное использование картографических API на уровне веб-домена.