Подпись запросов к API Яндекс Карт

Подпись запроса формируется с использованием секрета подписи URL-адреса. Этот секрет представляет собой закрытый 16-битный ключ.

Для подписания запросов используется алгоритм шифрования, объединяющий URL-адрес и секрет. В результате получается уникальная подпись, которая служит дополнительной гарантией безопасности ваших запросов.

Подпись отправляется в параметре signature вашего запроса в API (подробнее написано в секции Алгоритм подписи запроса). При неудачной проверке подписи возвращается код 403.

Включение подписи для запросов и получение секретов в Кабинете разработчика

Для начала нужно завести ключ для API в Кабинете разработчика. Про то, как это сделать, подробно описано здесь.

На странице конкретного API необходимо выбрать нужный ключ и перейти в его настройки (кнопка "изменить"):

Откроется окно настроек ключа. В нем нужно нажать на "Редактировать секреты". После этого откроется окно управления секретами и типами подписи:

Создание секрета

Для создания секрета необходимо нажать кнопку "Создать". После этого появится окно с новым сгенерированным секретом.

Важно

Этот секрет необходимо сохранить, просмотреть его еще раз не получится. В случае утери секрета сгенерируйте новый.

После этого в списке секретов появится новый сгенерированный секрет. В интерфейсе о секретах представлена следующая информация:

  1. Первые 4 символа ключа для идентификации
  2. Дата создания секрета
  3. Последнее использование секрета (обновляется от 15 минут до часа)

Про типы подписи в Кабинете разработчика

Кабинет поддерживает три вида подписи:

  • Подпись секретом и временем (WithTTL)
  • Подпись только секретом (WithoutTTL)
  • Опциональная (Optional)

Все три типа подписи могут быть включены одновременно. Они не являются взаимоисключающими.

Важно

Любые изменения в этой секции начинают влиять на проверку API-ключа через 15-60 минут.

Подпись секретом и временем (рекомендуется)

Эта опция позволяет включить подпись с ограничением на время действия. При включении этой опции требуется сначала подписать utc timestamp. Подробнее про алгоритм написано в секции Алгоритм подписи запроса

Подпись только секретом (не рекомендуется)

Эта опция позволяет включить подпись со стандартным алгоритмом. Подробнее про алгоритм написано в секции Алгоритм подписи запроса

Важно

Этот способ не рекомендуется использовать для подписи запросов на стороне клиента (из-за раскрытия секрета)

Опциональная (полезен при отладке и миграции)

Эта опция позволяет опционально подписывать запрос (каким-то из включенных способов выше). Это означает следующее:

  • При отправке подписи в запросе (через параметр signature) подпись будет проверена. При неудачной проверке вернется 403.
  • Если подпись отсутствует, запрос будет считаться валидным (с точки зрения проверки подписи).

Алгоритм подписи запроса

Есть два способа подписи запросов:

  • Подпись с ограничением на время действия
  • Обычная подпись

Для обоих способов необходимо сначала получить URL для подписывания. Алгоритм следующий:

  1. Необходимо сформировать URL без параметра signature. Запрос должен включать параметр apikey с ключом API. Пример: https://api-host/api?x=1&y=2&apikey=ffffffff-ffff-ffff-ffff-ffffffffffff
  2. Убрать из URL запроса хост. Именно этот url нужно подписывать. Пример: /api?x=1&y=2&apikey=ffffffff-ffff-ffff-ffff-ffffffffffff
  3. Необходимо иметь секрет из пункта Создание секрета (signing_secret). Выдается в закодированном виде с помощью Base64UrlSafe алгоритма (реализация в python). Необходимо преобразовать (раскодировать) секрет в бинарное представление.

В обоих случаях для подписи используется алгоритм HMAC с SHA256 хэш-функцией

Подпись с ограничением на время действия

Алгоритм вычисления подписи:

base64url(HMAC_SHA256(HMAC_SHA256(signing_secret, UTCTruncatedTimestamp), URL))

Мы гарантируем время работы подписи в один час. При этом подпись может работать до 3 часов включительно из-за особенностей реализации.

  1. Вычисляем текущий timestamp по UTC. Пример: 2025-10-08T14:59:21+0000
  2. Округляем timestamp до часов и приводим к строке вида YYYY-DD-MMTHH:00:00Z. Пример: 2025-10-08T14:00:00Z
  3. Подписываем эту строку с помощью секрета алгоритмом HMAC_SHA256. Получаем temporal_signing_secret (в байтах)
  4. Подписываем url с помощью секрета temporal_signing_secret алгоритмом HMAC_SHA256. Получаем подпись в байтовом представлении
  5. Кодируем подпись алгоритмом base64url
  6. Добавляем к URL запроса параметр signature с полученной подписью. Пример: https://api-host/api?x=1&y=2&apikey=ffffffff-ffff-ffff-ffff-ffffffffffff&signature=83OmiQMbnBUN6BV98_IZYRIVvU46OrsP5KJv4RdTsGw=

Важно

signature должен быть последним параметром в запросе

Обычная подпись

Алгоритм вычисления подписи:

base64url(HMAC_SHA256(signing_secret, URL))

Подробней по шагам:

  1. Подписываем url с помощью секрета signing_secret алгоритмом HMAC_SHA256. Получаем подпись в байтовом представлении
  2. Кодируем подпись алгоритмом base64url
  3. Добавляем к URL запроса параметр signature с полученной подписью. Пример: https://api-host/api?x=1&y=2&apikey=ffffffff-ffff-ffff-ffff-ffffffffffff&signature=HnIs8FNqyZwjN26Td0WQrb-IRtUFwXGzWhQ_1pftEkg=

Важно

signature должен быть последним параметром в запросе

Какие продукты поддерживают подпись запросов

Узнать, поддерживается ли подпись запросов для продукта, можно в Кабинете разработчика в настройках ограничений конкретного ключа или в документации к соответствующему продукту.