API-ключи и rate-limit
Одна рука держит ключ перед собой. Привязывайте каждый ключ к одному проекту, ротируйте и отзывайте его без секунды простоя, оставайтесь в rate-limit, под которые можно планировать. Сегодня работают и legacy-, и v2-ключи.
Legacy- и v2-ключи
Две модели живут бок о бок. Выбираете одну на проект; мы бы взяли v2.
Legacy
Один ключ на проект. RotateAPIKey заменяет его новым — значит, есть момент, когда старый ключ перестаёт работать, а новый начинает.
v2
Несколько именованных ключей на проект. CreateAPIKey добавляет ключ. RevokeAPIKey гасит один ключ по отдельности, а GetProjectByAPIKey определяет, какому проекту он принадлежит. Именно это даёт ротацию без разрыва.
Активны обе. Рекомендуем v2 — за множественные ключи и точечный отзыв.
Скоуп по проектам
Ключ принадлежит одному проекту внутри организации. Ни читать, ни двигать деньги другого он не может. Дайте каждому проекту и каждому окружению свой ключ. Тогда утечка остаётся в коробке: радиус поражения — этот один проект, а не весь аккаунт. Кто каким ключом владеет, решают роли — это на странице безопасности аккаунта.
Ротация и отзыв
На v2 порядок такой: сначала создаёте следующий ключ, переводите на него трафик и только потом зовёте RevokeAPIKey на старом — а значит, окна, где интеграция мертва, не бывает вовсе. RevokeAPIKey срабатывает сразу. Это ещё и ваша кнопка паники, едва ключ начал светиться. На legacy RotateAPIKey меняет единственный ключ на месте. В любом случае — ротация по расписанию и отзыв при первом намёке на утечку.
Запросы лимитированы по частоте. Превысите потолок — получите стандартную HTTP-ошибку, а не тихо потерянный вызов. Конкретное число мы тут не печатаем, пока оно не подтверждено в коде gateway: неверный лимит хуже, чем никакой. Заложите backoff на ошибку, и вы прикрыты в любом случае.
Точные лимиты: [TBD from code]
Аутентификация запроса
Передавайте ключ в заголовке X-Api-Key на каждом вызове. В примере — создание платежа на POST /v1/payments. Реальный ключ держите на сервере, не в браузере; вместо живого ключа в примере стоит плейсхолдер sk_live_....
curl -X POST https://api.suward.com/v1/payments \
-H "X-Api-Key: sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_abc_1" \
-d '{"amount":"25.00","asset":"USDC"}'Лучшие практики
Короткий список, и каждый пункт стоит сделать.
- 01
Держите ключи на сервере. Ключ в коде браузера или приложения — это уже утёкший ключ.
- 02
Свой ключ на проект и на окружение. Прод и staging не должны делить один секрет.
- 03
Ротируйте по расписанию и отзывайте, едва ключ начал светиться.
- 04
Никогда не коммитьте ключ в git. Немало утечек начинаются с секрета в публичном репозитории. Берите менеджер секретов или переменные окружения.
API-ключи — частые вопросы
Legacy даёт один ключ на проект, и RotateAPIKey его заменяет. v2 даёт несколько именованных ключей на проект — их создаёт CreateAPIKey, а отзывает по одному RevokeAPIKey. Именно эта разница и делает возможной ротацию без простоя.
Сначала создайте новый ключ через CreateAPIKey. Переведите на него трафик, убедитесь, что работает, потом отзовите старый через RevokeAPIKey. Интеграция не увидит разрыва.
Сразу отзовите его через RevokeAPIKey, затем выпустите замену через CreateAPIKey. Поскольку ключи скоупятся по проектам, утечка ограничена этим одним проектом, а остальные продолжают работать.