Токен авторизации в Честном Знаке: как получить, обновить и не потерять доступ к API

Токен авторизации в Честном Знаке - это временный ключ доступа, без которого ни один запрос к API ГИС МТ не будет выполнен. Отправляете коды в оборот, запрашиваете статусы КИ, передаёте документы отгрузки - каждый вызов API требует валидного токена в заголовке запроса. Токен истёк - все запросы возвращают 401 Unauthorized, интеграция встаёт, документы маркировки копятся в очереди. Разберём полный цикл: от первого получения до автоматического обновления.

Авторизация в API Честного Знака построена на двухэтапной схеме с использованием УКЭП (усиленной квалифицированной электронной подписи). Вы не просто отправляете логин-пароль - вы подписываете случайные данные своим закрытым ключом, доказывая, что являетесь владельцем сертификата. Система проверяет подпись и выдаёт токен. Это безопаснее, чем обычная пара логин-пароль, но технически сложнее. Именно на этом этапе у большинства участников возникают проблемы.

Как устроена авторизация в API Честного Знака: общая схема

Прежде чем погружаться в детали - разберём архитектуру. На март 2026 года актуален API v4 ГИС МТ. Авторизация проходит в два шага, каждый - отдельный HTTP-запрос.

Полученный токен передаётся в заголовке Authorization: Bearer {token} во всех последующих запросах. Без него API возвращает HTTP 401.

Пошаговое получение токена: от запроса до заголовка Authorization

Рассмотрим каждый шаг детально - с примерами запросов, указанием заголовков и типичных ошибок.

Шаг 1. Запрос данных для подписания (auth/key)

Отправляете GET-запрос на endpoint авторизации. Никаких заголовков аутентификации на этом этапе не нужно - запрос открытый.

GET https://markirovka.crpt.ru/api/v4/true-api/auth/key
// Ответ 200 OK:
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": "MIIБ...случайная_строка_Base64..."
}

Значение uuid - идентификатор сессии авторизации. Значение data - строка, которую нужно подписать вашим закрытым ключом УКЭП. Оба значения потребуются на втором шаге.

Шаг 2. Подписание данных с помощью УКЭП

Здесь начинается самое интересное. Значение data из ответа нужно подписать в формате CMS (PKCS#7) detached signature с использованием вашего сертификата УКЭП и закрытого ключа. Подпись должна быть в формате Base64.

Требования к подписи: формат CMS (PKCS#7), detached (отсоединённая подпись), алгоритм - ГОСТ Р 34.10-2012, кодировка - Base64. Сертификат должен быть зарегистрирован в Честном Знаке для вашей организации.

Как именно подписать - зависит от вашей технологии:

Шаг 3. Отправка подписи и получение токена (auth/simpleSignIn)

POST https://markirovka.crpt.ru/api/v4/true-api/auth/simpleSignIn
Content-Type: application/json

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": "MIIБ...подпись_в_Base64..."
}

// Ответ 200 OK:
{
  "token": "eyJhbGciOiJIUzI1NiIs...длинная_строка...",
  "life_time": 600
}

Поле token - ваш bearer-токен. Поле life_time - время жизни токена в секундах. По умолчанию для API v4 это 600 секунд (10 минут). После истечения - токен невалиден, нужно получать новый.

Шаг 4. Использование токена в запросах

GET https://markirovka.crpt.ru/api/v4/true-api/cises/info?cis=010460406000600021N4N57RCoo7e8
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Токен передаётся в заголовке Authorization с префиксом Bearer (с пробелом). Без этого заголовка или с просроченным токеном - ответ 401.

Время жизни токена: почему 10 минут и как с этим жить

600 секунд - жёсткий лимит. ЦРПТ установил короткое время жизни токена из соображений безопасности: даже если токен перехвачен, окно для злоупотребления минимально. Но для автоматизированных систем, которые непрерывно обмениваются данными с ГИС МТ, это создаёт необходимость регулярного обновления.

На практике это означает: ваша система должна каждые 8–9 минут (с запасом до истечения) проходить полный цикл авторизации заново - получить data, подписать, отправить, получить новый токен. Или обрабатывать ответ 401 и в этот момент перезапрашивать токен.

Две стратегии обновления токена

Рекомендация: комбинируйте обе стратегии. Основной механизм - проактивное обновление каждые 8 минут. Подстраховка - реактивный перехват 401 для случаев, когда таймер сбился или сервер отклонил токен раньше (бывает при рестарте серверов ГИС МТ).

Типичные ошибки при получении токена

Процесс авторизации прост на бумаге и коварен в реализации. Вот конкретные ошибки, с которыми сталкиваются разработчики и интеграторы.

Ошибка 401 при отправке подписи

Самая распространённая. Причины:

• Подписана не та строка. Нужно подписать значение поля data из ответа auth/key, а не весь JSON-ответ
• Подпись в неверном формате. Требуется CMS detached signature в Base64, а не attached или DER
• Сертификат не зарегистрирован в Честном Знаке. Сертификат должен быть привязан к организации в личном кабинете
• UUID протух. Между шагом 1 и шагом 2 прошло слишком много времени - uuid имеет ограниченный срок жизни (около 10 минут)
• Используется тестовый сертификат на продуктивном контуре (или наоборот)

Ошибка 400 Bad Request

Некорректный формат JSON в теле запроса. Проверьте: имена полей uuid и data - в нижнем регистре. Значение data - строка Base64 без переносов строк (или с корректными переносами, если API это допускает). Content-Type - строго application/json.

Ошибка 500 Internal Server Error

Проблема на стороне ГИС МТ. Повторите запрос через 1–5 минут. Если ошибка стабильная - проверьте статус технических работ в Telegram-канале Честного Знака. Бывает при плановых обновлениях серверов.

Ошибка «Сертификат не найден» или «Участник не зарегистрирован»

Сертификат, которым вы подписываете, не привязан к вашей организации в Честном Знаке. Зайдите в личный кабинет (markirovka.crpt.ru) → «Профиль» → «Сертификаты ЭП» и убедитесь, что текущий сертификат добавлен и активен. Если вы недавно получили новый сертификат - его нужно явно зарегистрировать.

Автообновление токена: примеры реализации

Ручное получение токена - для тестирования. В продуктивной среде обновление должно быть полностью автоматическим. Вот архитектурные подходы.

Подход 1: Token Manager (отдельный сервис)

Выделенный микросервис, который отвечает только за авторизацию. Хранит текущий токен в памяти, обновляет по таймеру. Все остальные сервисы обращаются к Token Manager за актуальным токеном через внутренний API. Преимущество: единая точка авторизации, нет дублирования логики подписания.

Подход 2: Middleware / Interceptor

HTTP-клиент перехватывает ответы 401 на уровне middleware. При получении 401 - автоматически запускает цикл авторизации, получает новый токен, повторяет исходный запрос с новым токеном. Реализуется в любом HTTP-клиенте: Axios interceptors (JavaScript), requests.Session hooks (Python), HttpClient DelegatingHandler (.NET).

Подход 3: Кэширование с TTL

Токен сохраняется в кэше (Redis, Memcached, in-memory) с TTL = life_time минус запас (например, 540 секунд при life_time 600). При запросе к кэшу - если токен есть и TTL не истёк, используется. Если нет - запрашивается новый. Подходит для распределённых систем, где несколько воркеров работают с одним API.

Токен авторизации в 1С: как работает «под капотом»

Пользователи 1С обычно не работают с токеном напрямую - модуль интеграции с ИС МП делает всё автоматически. Но когда что-то ломается - важно понимать, что происходит внутри.

1С выполняет ту же двухшаговую процедуру: запрашивает auth/key, подписывает данные через настроенный сертификат (используя КриптоПро CSP), отправляет подпись на auth/simpleSignIn, получает токен и хранит его в оперативной памяти сессии обмена. При истечении - повторяет цикл автоматически.

Когда авторизация в 1С ломается

• Сертификат не настроен или просрочен. Проверьте: Администрирование → Обмен электронными документами → Настройки электронной подписи и шифрования
• Ошибка 0x80090016. Контейнер закрытого ключа не найден - см. подробное решение в нашей статье об этой ошибке
• Устаревший модуль маркировки. Старая версия может использовать endpoint API v3, который уже не поддерживается. Обновите модуль
• Серверная 1С. Подписание происходит на сервере - сертификат и контейнер должны быть в профиле учётной записи службы агента сервера
• Прокси-сервер или файрволл. Блокирует исходящие HTTPS-запросы к markirovka.crpt.ru. Добавьте в исключения

Для диагностики: Администрирование → Обмен с ИС МП → Журнал обмена. Ищите записи с ошибкой авторизации. В детализации будет HTTP-код ответа и текст ошибки от ГИС МТ.

Тестовый и продуктивный контуры: разные endpoints, разные токены

ЦРПТ предоставляет два контура для работы с API. Токен, полученный на одном контуре, не работает на другом - это полностью изолированные среды.

Типичная ошибка: разработчик отлаживает интеграцию на demo.crpt.ru, всё работает. Переключает на продуктивный markirovka.crpt.ru - 401 Unauthorized. Причина: сертификат зарегистрирован только в тестовом контуре. Для продуктивного нужна отдельная регистрация организации и привязка сертификата.

Безопасность токена: что нужно знать

Bearer-токен - эквивалент временного пароля. Тот, кто им владеет, может выполнять любые операции от имени вашей организации в течение life_time.

• Не логируйте токен в открытом виде. Если логирование необходимо - маскируйте: показывайте только первые и последние 4 символа
• Не передавайте токен по незащищённым каналам. Только HTTPS. Никаких HTTP, никаких email с токенами
• Не храните токен в коде или конфигурационных файлах в репозитории. Используйте переменные окружения или vault
• Не делитесь токеном между организациями. Каждая организация должна получать свой токен своим сертификатом
• Мониторьте подозрительную активность. Если видите запросы, которые не инициировала ваша система - немедленно обновите сертификат

Rate limiting: ограничения на количество запросов авторизации

ГИС МТ ограничивает количество запросов авторизации от одного участника. Если ваша система слишком часто запрашивает новый токен (например, при каждом API-вызове вместо кэширования), сервер начнёт отклонять запросы с HTTP 429 Too Many Requests.

Точные лимиты ЦРПТ не публикует в открытом доступе, но практика показывает: запрашивать токен чаще, чем раз в минуту, не стоит. При стандартном life_time 600 секунд одного обновления каждые 8–9 минут более чем достаточно.

Отладка: как убедиться, что авторизация работает

Перед запуском в продуктивную среду - протестируйте авторизацию изолированно. Вот чек-лист.

Тарифы на услуги маркировки

Настройка интеграции с API, авторизация, подписание, автообновление токенов - всё это требует квалификации разработчика с опытом работы с криптографией и ГИС МТ. Актуальные тарифы на настройку и сопровождение - на mark-guru.ru.

[tariffs_block]

Частые вопросы и ответы

Что такое токен авторизации в Честном Знаке?

Это временный bearer-токен, который выдаётся после двухэтапной авторизации через УКЭП. Токен передаётся в заголовке Authorization каждого запроса к API ГИС МТ и подтверждает, что вы - зарегистрированный участник маркировки.

Сколько действует токен авторизации?

По умолчанию - 600 секунд (10 минут). Значение возвращается в поле life_time ответа на auth/simpleSignIn. После истечения токен невалиден, и нужно получать новый через полный цикл авторизации.

Можно ли продлить время жизни токена?

Нет. ЦРПТ не предоставляет возможность изменить life_time или использовать refresh-токен для продления. Каждый раз нужно проходить полный цикл: auth/key → подписание → auth/simpleSignIn.

Почему на шаге auth/simpleSignIn возвращается 401?

Основные причины: подписаны не те данные (нужно подписывать значение поля data, а не весь JSON), подпись в неверном формате (нужен CMS detached Base64), сертификат не зарегистрирован в Честном Знаке, uuid протух (прошло слишком много времени между шагами).

Как подписать данные для авторизации через командную строку?

Используйте утилиту cryptcp от КриптоПро: сохраните значение data в файл, затем выполните cryptcp -signf -cert -der -detached -thumbprint [отпечаток_сертификата] [файл]. Результат - файл с подписью, содержимое которого нужно закодировать в Base64.

Нужен ли отдельный токен для каждой товарной группы?

Нет. Один токен авторизации даёт доступ ко всем товарным группам, в которых зарегистрирована ваша организация. Разделение идёт на уровне endpoints и параметров запроса, а не на уровне авторизации.

Как работает авторизация в 1С - нужно ли получать токен вручную?

Нет, модуль интеграции 1С с ИС МП делает это автоматически. Вы настраиваете сертификат ЭЦП один раз - дальше 1С сама проходит авторизацию, получает и обновляет токен при каждом сеансе обмена.

Можно ли использовать один токен из нескольких приложений одновременно?

Да, bearer-токен не привязан к IP-адресу или конкретному клиенту. Его можно использовать из нескольких процессов одновременно, пока не истёк life_time. Но при получении нового токена старый не аннулируется - он продолжает работать до истечения своего life_time.

Что произойдёт, если получить новый токен, пока старый ещё действует?

Оба токена будут действительны до истечения их индивидуальных life_time. Новый токен не аннулирует старый. Это позволяет безопасно обновлять токен до истечения текущего - без разрыва для текущих запросов.

Чем отличается авторизация в тестовом и продуктивном контурах?

Механизм абсолютно идентичен. Различаются только Base URL (demo.crpt.ru vs markirovka.crpt.ru) и набор зарегистрированных сертификатов. Сертификат, работающий на тестовом контуре, не будет принят на продуктивном - и наоборот.

Как понять, что токен истёк, а не произошла другая ошибка?

Истёкший токен возвращает HTTP 401 Unauthorized. Но 401 может возвращаться и по другим причинам (невалидный токен, неверный формат заголовка). Проверяйте: если запросы работали и внезапно стали возвращать 401 - скорее всего, токен истёк. Если 401 с самого начала - проблема в процессе авторизации.

Существует ли refresh-токен в API Честного Знака?

Нет. В отличие от OAuth 2.0 с его access/refresh-токенами, API Честного Знака не поддерживает refresh-токен. Для получения нового auth-токена нужно каждый раз проходить полный цикл с подписанием данных через УКЭП.

Главное: токен - это ваш пропуск в ГИС МТ, и он постоянно обновляется

Авторизация в API Честного Знака - не «настроил и забыл». Это непрерывный процесс: получил токен → использовал → через 10 минут получил новый. Выстройте надёжный механизм автообновления, обеспечьте доступность сертификата и контейнера ключей, обработайте все edge-случаи (401, 500, таймауты) - и интеграция будет работать бесперебойно.

Информация актуальна на март 2026 года. Нормативная база: Федеральный закон № 487-ФЗ, документация API v4 ГИС МТ (ЦРПТ), Федеральный закон № 63-ФЗ «Об электронной подписи». Endpoints, параметры и формат авторизации могут быть обновлены ЦРПТ - рекомендуется сверять с актуальной документацией на портале Честного Знака.