Ключ API — секрет, идентифицирующий учётную запись при обращении к SMS API; он передаётся как Bearer-токен с ограниченными правами, создаётся отдельно для каждой системы и отзывается при компрометации.
Ключ API — это пароль для программ: длинная случайная строка, которая идентифицирует учётную запись и несёт набор прав. В отличие от пароля человека, им пользуются машины, без второго фактора, поэтому его защита зависит от того, как ключ выдаётся, хранится и ограничивается. Грамотная реализация показывает ключ один раз при создании и хранит только его хеш, позволяет задать, что именно ему разрешено делать, может привязать его к списку разрешённых IP-адресов и отзывает его мгновенно. Узнаваемый префикс, например обозначающий рабочие или тестовые ключи, помогает людям и сканерам секретов заметить ключ, утёкший в репозиторий или журнал.
Рабочее правило — один ключ на каждую систему и среду, с минимальными правами, которых достаточно для работы. Ключам место в переменных окружения или в менеджере секретов и никогда — в клиентском коде, мобильном приложении или системе контроля версий. Ротация — обычная процедура: создайте новый ключ, разверните его, отзовите старый. Утечку устраняют так же, но немедленно.
Пример
В условной компании работают сервис оформления заказов, который только отправляет коды, и задача формирования отчётов, которая только читает статусы. Сервис оформления заказов получает рабочий ключ с правом отправки, разрешённый только для двух его серверов; задача отчётов — ключ только для чтения; на тестовом стенде используется тестовый ключ. Когда ключ отчётов обнаруживается в публичном журнале, с ним нельзя отправить ни одного сообщения, а его замена затрагивает лишь одну систему.
Типичные ошибки
- Встраивать ключ в веб-страницу или приложение, откуда его может извлечь кто угодно.
- Использовать один ключ во всех системах, из-за чего при утечке менять его приходится везде.
- Записывать в журнал заголовки запросов целиком, а вместе с ними и ключ.
- Запускать автотесты с рабочим ключом.
В SMSMeteor: ключи создаются в панели, показываются один раз и передаются как bearer-токены с префиксом sk_live_ или sk_test_. Им выдаются права send, read или оба, а ключ можно ограничить списком разрешённых IP-адресов; запросы с других адресов получают 401 unauthorized. Тестовые ключи проверяют запрос, рассчитывают цену и отвечают так же, как рабочие, возвращают статус test и никогда ничего не отправляют и не списывают. См. также страницу безопасности.
