Mapbox GL JS использует модель доступа на основе токенов, в которой каждая операция взаимодействия с картографическими сервисами Mapbox требует предъявления валидного access token. Эта модель построена вокруг нескольких типов токенов, различающихся сроком жизни, уровнем привилегий и способом выдачи. На практике особую роль играют краткоживущие или временные токены, позволяющие существенно снизить риски компрометации ключей в клиентских приложениях.
Токен доступа в Mapbox представляет собой строку, которая передаётся в Mapbox GL JS при инициализации карты и используется для:
Типичный публичный токен передаётся в клиентский код:
mapboxgl.accessToken = 'pk.eyJ1Ijoiexample"...';Такие токены начинаются с префикса pk. (public token) и
обычно используются непосредственно в браузере. Их главный недостаток —
долговременная валидность, из-за чего компрометация приводит к
длительному несанкционированному доступу.
Размещение постоянного access token в клиентском JavaScript создаёт несколько системных рисков:
Особенно критично это в SPA и публичных веб-картах, где исходный код полностью доступен пользователю.
Эта проблема привела к появлению концепции временных токенов.
Временный токен представляет собой access token с ограниченным сроком жизни (TTL — time to live). Он выдаётся серверной частью приложения и используется клиентом только в течение короткого интервала времени.
Основные характеристики:
Такая модель делает утечку токена значительно менее критичной.
Типичная схема взаимодействия включает три компонента:
Поток выглядит следующим образом:
Сервер обычно использует секретный токен (sk.), который
никогда не попадает в браузер. На его основе создаётся ограниченный
токен.
Пример серверной логики (Node.js):
import fetch from 'node-fetch';
async function createTemporaryToken() {
const response = await fetch('https://api.mapbox.com/tokens/v2', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
expires: '2026-06-01T12:00:00Z',
scopes: [
'styles:read',
'fonts:read',
'datasets:read'
],
allowedUrls: ['https://example.com']
})
});
const data = await response.json();
return data.token;
}Ключевые параметры:
expires — время истечения токенаscopes — набор разрешенийallowedUrls — ограничение по доменамПосле получения токена он передаётся в клиент:
mapboxgl.accessToken = TEMPORARY_TOKEN;
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v12',
center: [69.2401, 41.2995],
zoom: 10
});Mapbox GL JS автоматически использует этот токен для всех сетевых запросов, включая загрузку:
Одним из ключевых механизмов безопасности является ограничение токена по контексту использования.
"allowedUrls": [
"https://app.example.com",
"https://admin.example.com"
]Такой токен не будет работать при попытке использования на другом домене.
Scopes определяют, какие операции разрешены:
styles:readtiles:readfonts:readdatasets:readОтсутствие лишних прав уменьшает поверхность атаки при утечке токена.
Поскольку временные токены имеют ограниченный срок действия, требуется механизм обновления без перезагрузки приложения.
Типовой подход:
Пример логики обновления:
async function refreshTokenIfNeeded() {
const newToken = await fetch('/api/mapbox-token').then(r => r.text());
mapboxgl.accessToken = newToken;
}В более сложных системах обновление синхронизируется с жизненным циклом сессии пользователя.
В экосистеме Mapbox выделяются три уровня токенов:
pk.sk.В одностраничных приложениях (SPA) временные токены часто интегрируются через слой API:
/api/mapbox-tokenЭто позволяет связывать доступ к карте с пользовательской сессией.
Несмотря на наличие временных токенов, остаются распространённые проблемы:
Размещение sk. токена в frontend полностью
компрометирует систему.
Даже временный токен без allowedUrls может быть
использован вне контекста приложения.
Токен с длительным сроком жизни фактически эквивалентен постоянному ключу.
CDN или браузерный кэш могут сохранять устаревшие токены, что приводит к ошибкам доступа.
В продвинутых системах временные токены привязываются к пользователям:
Логика генерации токена может учитывать:
При истечении срока действия токена библиотека:
Поэтому обновление токена должно быть синхронизировано с жизненным циклом карты.
Частая генерация токенов увеличивает нагрузку на сервер. Для оптимизации применяются:
В крупных приложениях временные токены становятся частью общей архитектуры безопасности:
Такая модель особенно важна для систем с высокой нагрузкой, где Mapbox GL JS используется как основной рендеринг картографического слоя.