Работа с токенами

В экосистеме Mapbox доступ к картографическим сервисам строится вокруг механизма токенов. В библиотеке Mapbox GL JS токены являются обязательным элементом и используются для авторизации всех запросов к стилям, тайлам, геокодированию и другим API.

Токен в Mapbox — это строка доступа, которая связывает клиентское приложение с конкретным аккаунтом, проектом и набором разрешений. Без корректного токена библиотека не сможет загрузить карту, стили или данные.

Типы токенов и их назначение

Public access token

Публичный токен используется в клиентском коде браузера и является основным способом подключения Mapbox GL JS к сервисам.

Ключевые характеристики:

  • предназначен для использования на стороне клиента;
  • не должен предоставлять административных прав;
  • ограничивается доменами и scope’ами;
  • используется в каждом запросе карты.

Пример:

mapboxgl.accessToken = 'pk.eyJ1IjoidXNlciIsImEiOiJ0b2tlbiJ9.example';

Префикс pk. указывает на публичный характер токена.

Secret access token

Секретный токен применяется на серверной стороне и не должен попадать в браузерный код.

Основные свойства:

  • доступ к административным API;
  • возможность создания и управления токенами;
  • использование в CI/CD, backend-сервисах;
  • префикс sk..

Пример серверного использования:

import fetch from 'node-fetch';

const token = process.env.MAPBOX_SECRET_TOKEN;

const response = await fetch(
  `https://api.mapbox.com/tokens/v2?access_token=${token}`
);

const data = await response.json();

Привязка токена к Mapbox GL JS

В Mapbox GL JS токен задаётся глобально через объект mapboxgl.

import mapboxgl from 'mapbox-gl';

mapboxgl.accessToken = 'pk.example.token.value';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [69.2401, 41.2995],
  zoom: 10
});

Без установки mapboxgl.accessToken библиотека не выполнит загрузку стиля и тайлов.

Механизм использования токена в запросах

Каждый запрос Mapbox GL JS к API автоматически включает токен в query string:

https://api.mapbox.com/styles/v1/mapbox/streets-v12?access_token=...

Аналогично для:

  • векторных тайлов;
  • растровых тайлов;
  • sprite-ресурсов;
  • glyphs (шрифтов);
  • tileset запросов.

Ограничения токенов (Token Scopes)

Scopes определяют, какие операции разрешены токену.

Распространённые scope:

  • styles:read — доступ к стилям
  • tiles:read — доступ к тайлам
  • fonts:read — загрузка шрифтов
  • datasets:read/write — работа с датасетами
  • uploads:write — загрузка данных

Пример логики ограничения:

  • токен с styles:read не сможет загружать кастомные датасеты;
  • токен без tiles:read не отрисует карту.

Ограничение по доменам (URL restrictions)

Токены часто привязываются к списку разрешённых доменов.

Пример конфигурации:

  • localhost
  • example.com
  • app.domain.com

При несоответствии домена запрос блокируется на стороне Mapbox API.

Это критически важный механизм защиты публичных токенов.

Хранение токена в проекте

Переменные окружения

Практика хранения токена в .env:

MAPBOX_ACCESS_TOKEN=pk.example.token

Использование в коде:

mapboxgl.accessToken = process.env.MAPBOX_ACCESS_TOKEN;

Конфигурационные модули

export const config = {
  mapboxToken: 'pk.example.token'
};

Безопасность токенов

Основная модель безопасности Mapbox основана на разделении токенов:

  • публичный токен допустим в браузере;
  • секретный токен никогда не должен попадать в клиентский код;
  • ограничения по домену уменьшают риск утечки;
  • ограничения по scope уменьшают потенциальный ущерб.

Типовые угрозы:

  • утечка sk. токена в репозитории;
  • отсутствие domain restriction;
  • использование одного токена для всех приложений.

Ротация токенов

Ротация применяется при:

  • компрометации токена;
  • изменении архитектуры приложения;
  • переходе на новые scope;
  • разделении окружений (dev/staging/prod).

Процесс:

  1. создание нового токена;
  2. обновление переменных окружения;
  3. деплой;
  4. деактивация старого токена.

Динамическое обновление токена

В некоторых приложениях токен может меняться без пересборки.

Пример:

function initializeMap(token) {
  mapboxgl.accessToken = token;

  return new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/light-v11'
  });
}

Такой подход используется в multi-tenant системах.

Использование токенов в стилях

Стиль Mapbox также требует токен для загрузки ресурсов.

style: 'mapbox://styles/mapbox/outdoors-v12'

Внутри стиля присутствуют ссылки на:

  • tileset’ы;
  • sprites;
  • glyphs;

Все они требуют валидного токена при запросе.

Ошибки, связанные с токенами

Invalid token

Причины:

  • опечатка в строке;
  • истёкший токен;
  • удалённый токен в аккаунте.

Missing token

Симптом:

  • карта не загружается;
  • консоль содержит ошибки авторизации.

Unauthorized domain

Причины:

  • токен ограничен доменами;
  • приложение запущено на localhost без разрешения.

Использование токенов в SSR и backend

В server-side rendering токен может использоваться для:

  • генерации статических карт;
  • получения тайлов;
  • геокодинга.

Пример SSR запроса:

const url = `https://api.mapbox.com/geocoding/v5/mapbox.places/Almaty.json?access_token=${process.env.MAPBOX_SECRET_TOKEN}`;

Разделение окружений

Практика использования разных токенов:

  • development — без строгих ограничений
  • staging — ограниченные scope
  • production — строгие domain restrictions

Пример конфигурации:

const tokens = {
  dev: 'pk.dev.token',
  prod: 'pk.prod.token'
};

mapboxgl.accessToken = tokens[process.env.NODE_ENV];

Работа с несколькими токенами

В крупных приложениях возможно использование:

  • разных токенов для разных микросервисов;
  • отдельных токенов для аналитики и рендеринга;
  • изоляции команд разработки.

Принцип минимальных привилегий

Токен должен содержать только необходимые права:

  • только чтение для фронтенда;
  • запись только для серверных процессов;
  • отдельные токены для загрузки данных.

Это снижает риск несанкционированного доступа и упрощает аудит безопасности.

Токены и кэширование

Mapbox активно кэширует ресурсы, однако:

  • изменение токена может привести к сбросу кэша;
  • разные токены могут создавать разные cache keys;
  • CDN учитывает токен в запросе.

Интеграция токена в сборщики

Webpack

new webpack.DefinePlugin({
  'process.env.MAPBOX_TOKEN': JSON.stringify(process.env.MAPBOX_TOKEN)
});

Vite

export default defineConfig({
  define: {
    __MAPBOX_TOKEN__: JSON.stringify(process.env.MAPBOX_TOKEN)
  }
});

Логирование и диагностика токенов

При отладке полезно отслеживать:

  • статус ответа API;
  • заголовки ошибок;
  • тип токена (pk/sk);
  • доменные ограничения.

Эволюция модели токенов Mapbox

Архитектура токенов развивалась от простого API key к системе:

  • granular scopes;
  • domain restrictions;
  • token rotation;
  • fine-grained access control.

Это позволило использовать Mapbox GL JS в корпоративных системах с высокими требованиями к безопасности.

Оглавление