API-ключ — это пароль для программы. А ещё это право тратить деньги: кто владеет ключом, тот может расходовать ваш баланс.
Как это работает
LLM API считают ключ bearer-токеном. Клиент отправляет его с каждым запросом:
curl https://inference.broadnet.ai/v1/models \
-H "Authorization: Bearer $BROADNET_API_KEY"
RFC 6750 определяет bearer-токен как такой, которым может воспользоваться “any party in possession of the token” (перевод: «любая сторона, у которой есть токен»). Второго фактора нет. Поэтому тот же RFC требует, чтобы клиенты всегда передавали bearer-токены по TLS (https://).
Провайдер находит ключ, определяет аккаунт, проверяет лимиты и политики, а затем выполняет или отклоняет запрос. Отсутствующий или неверный ключ обычно даёт 401; ключ, отклонённый политикой, например белым списком IP, — обычно 403.
Почему это важно
Утечка ключа — одна из самых частых причин того, что счёт за API выходит из-под контроля: боты сканируют публичный код в поисках секретов. Утечка может раскрыть и данные, если ключ даёт доступ к эндпоинтам, которые возвращают сведения об аккаунте. Хорошие практики, в духе рекомендаций OWASP по управлению секретами:
- Загружайте ключи из переменных окружения или менеджера секретов. Никогда не коммитьте их и не зашивайте в образы контейнеров.
- Дайте каждому приложению или агенту свой ключ, чтобы отзывать один, не останавливая всё.
- Меняйте ключи по расписанию и сразу при подозрении на утечку.
- Ограничьте, откуда ключ работает, например белым списком IP серверов.
В BroadNet Inference
BroadNet разделяет два вида учётных данных. Ключ для инференса вызывает модели на /v1/*. Учётные данные портала автоматизируют управление аккаунтом: ключи, разрешённые IP и покупки. Относитесь к ним как к полному доступу к аккаунту.
Оба показываются один раз. BroadNet хранит только хеш SHA-256, поэтому показать ключ повторно не может. Ключ с оплатой по факту действует один год, а на аккаунте может быть до десяти действующих ключей. У каждого ключа может быть свой список разрешённых IP. После отзыва ключа или изменения белого списка новые запросы перестают проходить в течение пяти секунд.
Ключи тарифов с фиксированной ценой отдельные и никогда не списывают средства с баланса. Порядок настройки — в руководстве API-ключи и белые списки IP, коды статусов — в руководстве ошибки и повторные запросы.
Частые ошибки
- Записывать в лог заголовки запроса целиком. Так ключ попадает в логи.
- Использовать один ключ на всю команду. Тогда нельзя отозвать доступ у одного человека.
- Отправлять ключ в поддержку. Вместо него отправьте значение заголовка
X-Request-ID.