Ключ показывается один раз: как команде хранить, менять и отзывать API-ключи
Когда вы выпускаете API-ключ в кабинете SimAggregator, его строка появляется на экране один раз. Если закрыть окно, не скопировав её, увидеть строку снова не сможет никто, включая нас: платформа хранит только отпечаток ключа, а не саму строку. Потерянный ключ не восстанавливают, его заменяют: выпускают новый и отзывают старый. Поэтому ротацию и отзыв стоит наладить заранее, пока ничего не утекло.
Один ключ на одну среду и один сервис
Ключ действует от имени вашего аккаунта и тратит его баланс: у кого оказалась строка, тот может покупать номера за ваш счёт. С одним общим ключом «на всё» при утечке непонятно, где она случилась, а отзыв ломает сразу все интеграции.
В кабинете можно выпустить несколько ключей и дать каждому имя. Мы советуем схему «среда + сервис»: prod-bot, staging-bot, ci-tests. По имени сразу видно, что перестанет работать после отзыва и кого спрашивать о странной активности. Лимит API, 600 запросов в минуту, считается на ключ, поэтому прогон тестов в CI не отнимает запросы у боевого сервиса.
С CI есть тонкость: getNumber оттуда покупает настоящие номера с того же баланса. Отменить такой заказ можно не раньше чем через минуту. Заказы, отменённые без кода, снижают долю заказов с кодом за 7 дней, а по репутации аккаунта считается лимит одновременных заказов, общий для CI и боевого бота. Для smoke-проверок обычно хватает getBalance и getPrices.
Где хранить строку ключа
Сразу после выпуска кладите ключ в секрет-менеджер или в защищённые переменные CI с маскированием в логах. Не в репозиторий, не в .env, закоммиченный «временно», не в рабочий чат и не в тикет. Разработчику, который пишет интеграцию, строка боевого ключа обычно не нужна: сервис сам забирает её из хранилища при старте.
API совместим с sms-activate и принимает только GET-запросы, поэтому ключ передаётся в строке запроса. Проверьте, что HTTP-клиент, прокси и access-логи не записывают адрес запроса целиком. Логи хранятся долго и доступны многим, так что ключ, попавший в лог, считайте утёкшим.
Ротация: сначала новый ключ, потом отзыв старого
Ротация состоит из двух действий в кабинете: выпуск нового ключа и отзыв старого. В таком порядке старый ключ работает, пока сервис не переключился на новый, и запросы не падают.
- Выпустите новый ключ с тем же назначением в имени, например
prod-bot-2. - Запишите его в секрет-менеджер вместо старого значения.
- Перезапустите сервис, чтобы он подхватил новый ключ.
- Проверьте в кабинете: у нового ключа появилась дата последнего использования, у старого она больше не меняется.
- Отзовите старый ключ.
Внеплановая ротация нужна, если:
- из команды ушёл человек, который видел ключ;
- ключ попал в лог, скриншот, переписку или репозиторий;
- вы переехали на другой хостинг или CI.
Плановую ротацию привяжите к графику, по которому у вас меняются остальные секреты.
Аудит по дате последнего использования
Открывайте список ключей перед релизом или при пересмотре доступов. Ключ, которым давно не пользовались, скорее всего остался от закрытого проекта: отзовите его. Если ключом staging-bot пользуются, а сам staging-бот остановлен неделю назад, отзывайте сразу и выясняйте, откуда идут запросы. Ключ с непонятным именем тоже проще отозвать, чем гадать, чей он. Если он кому-то нужен, владелец заметит это по своему сервису и выпустит новый ключ с понятным именем.
Защитите сам аккаунт
Безопасность API-ключа упирается в безопасность аккаунта: кто вошёл в кабинет, тот может выпустить себе новый ключ и тратить баланс. Поэтому включите двухфакторную аутентификацию: TOTP-код из приложения-аутентификатора настраивается на странице входа, там же меняется пароль. Если есть подозрение, что в аккаунт входил посторонний, завершите сеансы на других устройствах, смените пароль и проведите ротацию всех ключей. Тот же порядок подходит, когда из команды уходит человек, у которого был доступ к кабинету.
Для начала включите 2FA на странице входа. Затем выпустите в кабинете отдельные именованные ключи для prod, staging и CI, разложите их по секрет-менеджеру и отзовите общий ключ, если он у вас был.