← Все статьи
Руководство

Как заменить API-ключ UnifyPort без простоя

Чтобы заменить API-ключ UnifyPort без простоя, не вызывайте endpoint rotate первым действием. После успешного POST /v1/api-keys/{key_id}/rotate старый ключ сразу становится недействительным. Вместо этого создайте второй активный ключ, сохраните секрет, который показывается один раз, разверните его во всех сервисах, проверьте через GET /v1/workspace и только затем переведите старый ключ в inactive.

Главное

  • Endpoint rotate выполняет мгновенное переключение без льготного периода для старого ключа.
  • Для замены без простоя два ключа ненадолго остаются активными: создание, развертывание, проверка, отключение.
  • Полный новый секрет возвращается в data.api_key только один раз; получить его позднее нельзя.
  • Список ключей содержит key_prefix, статус и другие метаданные, но не полный секрет.
  • Для обычного поэтапного развертывания создавайте новый ключ и затем отключайте старый. Rotate нужен при намеренном немедленном отзыве.

Почему rotate может прервать работу production

Справочник Rotate API key определяет операцию:

POST /v1/api-keys/{key_id}/rotate

Она создает новую запись ключа, один раз возвращает новый секрет и одновременно делает старый ключ недействительным. Это полезно, если прежние учетные данные могли стать известны посторонним. Но если веб-процессы, обработчики очередей, задачи по расписанию или экземпляры в другом регионе продолжают читать старое значение, они начнут получать 401 invalid_api_key.

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

NIST SP 800-53 включает изменение и обновление аутентификаторов в общий контекст управления ими. Однако практическая последовательность должна учитывать реальный контракт продукта: UnifyPort допускает несколько записей API-ключей, а rotate немедленно аннулирует предшествующий ключ.

Инструкция по замене API-ключа без простоя

1. Найдите всех потребителей ключа

Перечислите все компоненты, которые отправляют X-Api-Key на https://api.unifyport.ai: публичное приложение, фоновые процессы, webhook-задачи с ответными вызовами, задания по расписанию, производственные инструменты и проверки состояния.

Не путайте API-ключ с webhook-параметром signing_secret. Первый аутентифицирует ваши запросы к REST API UnifyPort. Второй нужен для проверки webhook-доставок, которые приходят в ваше приложение. Отдельный путь описан в руководстве по HMAC, защите от повторной доставки и повторам запросов.

Просмотрите записи через List API keys:

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

Ответ содержит id, name, key_prefix и status, но намеренно не раскрывает полный секрет.

2. Создайте второй активный ключ

Используйте Create API key, а не rotate:

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

Успешный ответ 201 возвращает метаданные в data.key, а полный новый секрет — в data.api_key. Сразу поместите его в одобренное хранилище секретов. Не выводите значение в журналы развертывания, заявки или чаты.

Если одноразовое значение потеряно до развертывания, создайте еще один ключ и отключите неиспользованную запись. Восстановить полный секрет из префикса невозможно.

3. Проверьте новый ключ до развертывания

Выполните безопасную операцию чтения с новым секретом:

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

Успешный ответ подтверждает, что новый ключ относится к рабочему пространству. Он не доказывает, что каждый экземпляр приложения уже загрузил значение.

Обновите ссылку на секрет в конфигурации и поэтапно разверните ее для каждого типа потребителей. Пока развертывание не завершено, оставляйте старый ключ в состоянии active. В журнале изменения отмечайте версии, группы экземпляров и ответственных, но не значения секретов.

4. Убедитесь, что весь парк использует новый ключ

Перед отключением старого ключа проверьте:

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

Опирайтесь на результаты запросов приложения и состояние развертывания. Список ключей UnifyPort показывает метаданные и статус, но документация не описывает аналитику последнего использования по каждому ключу. Не делайте вывод о завершении миграции из данных, которых endpoint не возвращает.

Командам, которые начали работу через интерфейс управления, полезна статья о dashboard и управлении API-ключами. Эта инструкция дополняет ее порядком действий для работающей системы.

5. Отключите старый ключ

Когда каждый потребитель использует новый секрет, вызовите Update API key status с новым ключом:

curl -X PATCH "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

Документированные состояния — active и inactive. После отключения выполните один контролируемый запрос на чтение со старым секретом и убедитесь, что он получает 401 invalid_api_key. Не используйте реальную клиентскую операцию для этой проверки.

Затем удалите старое значение из конфигурации развертывания, локальных файлов окружения, переменных CI и временных материалов миграции. В операционной записи оставьте только несекретные данные: ID, имя, статус ключа, ответственного и время переключения.

Когда нужен немедленный rotate

Применяйте POST /v1/api-keys/{key_id}/rotate, если мгновенная недействительность старых учетных данных является требованием. Например, секрет мог стать доступен посторонним либо все потребители могут синхронно переключиться в окно обслуживания.

Последовательность будет другой:

  1. остановите или изолируйте потребителей со старым ключом;
  2. вызовите rotate из контролируемого операторского контура;
  3. один раз сохраните data.api_key;
  4. обновите всех потребителей секрета;
  5. верните трафик и проверьте аутентификацию.

Здесь скорость отзыва важнее непрерывной доступности. Если есть подозрение на раскрытие секрета, не продлевайте период действия двух ключей только ради трафика — следуйте правилам реагирования вашей команды.

Ограничения и компромиссы

Во время короткого периода перекрытия обе учетные записи авторизуют доступ к рабочему пространству. Сократите это окно до практического минимума и ограничьте доступ к секретам. Введение UnifyPort указывает, что X-Api-Key разрешается в одно рабочее пространство и дает доступ в его пределах; это не миграция разрешений для отдельных endpoint.

Инструкция не меняет webhook signing_secret, данные входа в платформы или импортированные сессии. У каждого типа секрета свои потребители и сценарии отказа, поэтому их следует менять и проверять отдельно.

FAQ

Есть ли у rotate льготный период для старого ключа?

Документированный endpoint rotate не предусматривает такой период. Старый ключ становится недействительным сразу после успеха. Для перекрытия сначала создайте второй ключ.

Можно ли повторно получить новый API-ключ позднее?

Нет. Полное значение возвращается в data.api_key один раз. Последующие списки показывают только префикс, статус и другие метаданные.

Как безопасно проверить новый ключ?

Вызовите GET /v1/workspace с новым X-Api-Key, затем убедитесь, что каждый развернутый потребитель загрузил этот секрет, и только после этого отключайте старую запись.

Что выбрать: rotate или создание с последующим отключением?

Для обычного поэтапного развертывания — создание и последующее отключение. Rotate подходит при намеренном немедленном отзыве после изоляции всех старых потребителей.

API-ключ и signing_secret — одно и то же?

Нет. X-Api-Key аутентифицирует вызовы REST API, а signing_secret используется для проверки HMAC-SHA256 подписи webhook.

Следующий шаг

Откройте Create API key, создайте параллельный production-ключ и пройдите все пять проверок до изменения статуса старого ключа.

Источники

Проверено 17 августа 2026 года.