Что такое API-ключ и как им пользоваться

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

Ниже — как ключ устроен, чем он отличается от пароля, где его держать и какие ошибки вокруг него встречаются чаще всего.

Зачем вообще нужен ключ

У любого платного сервиса есть три задачи: понять, кто пришёл, проверить права и выставить счёт. С человеком это решается формой входа. С программой форма не работает: некому вводить пароль в три часа ночи, когда сработал планировщик.

Ключ закрывает все три задачи одной строкой. Он приходит в заголовке запроса, сервис сверяет его со своей базой и дальше знает владельца, лимиты и баланс.

Как это выглядит на практике

Ключ подставляется в заголовок Authorization со словом Bearer перед ним.

curl https://api.keydealer.ru/v1/models \
  -H "Authorization: Bearer $KEYDEALER_API_KEY"

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

Чем ключ отличается от пароля

Три отличия, из которых следует всё остальное.

Ключей много, пароль один. Можно выпустить отдельный ключ на каждое приложение и отозвать любой по отдельности.

Ключ не восстанавливается. Секрет показывается один раз при создании. Потеряли — выпускаете новый, старый отзываете.

Ключ действует без участия человека. Это его смысл и его же главный риск: утёкший ключ работает молча, пока вы не заметите расход.

Где хранить

Правильный ответ короткий: в переменной окружения или в менеджере секретов, который умеет их выдавать приложению во время запуска.

Что считается небезопасным хранением:

1. В коде. Даже во внутреннем репозитории и даже «временно, на один день».
2. В конфиге, который лежит рядом с кодом, если этот конфиг не исключён из репозитория явно.
3. В переписке. Ключ, отправленный в мессенджер, считается скомпрометированным.
4. В браузере на клиенте. Всё, что уехало во фронтенд, доступно любому посетителю через инструменты разработчика.

Последний пункт объясняет, почему вызовы к моделям делаются с сервера, а не из браузера. Подробный разбор сценариев хранения — в статье как хранить API-ключи.

Как ограничить ущерб заранее

Ключ — это доступ к деньгам, поэтому у него должны быть границы, выставленные до первого запроса, а не после первого счёта.

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

Потолок расхода. Агент в цикле или ошибка в ретраях тратят баланс быстрее, чем это заметно на глаз.

Журнал запросов. Когда счёт вырастет вдвое, ответ на вопрос «какой сценарий это сделал» должен находиться запросом к журналу. Как его вести — в статье логирование запросов к моделям.

Регулярная ротация. Раз в несколько месяцев ключи имеет смысл перевыпускать, особенно после ухода людей из проекта.

Ключ в команде: кто его держит

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

Так делать не стоит по трём причинам. Расход перестаёт быть разделимым: вы видите общую сумму и не знаете, чей сценарий её сделал. Отзыв становится болезненным: отзываете один ключ и ломаете работу всем сразу. И утечка перестаёт быть локализуемой: ключ, побывавший в переписке, мог уехать куда угодно.

Рабочая схема простая. Ключ прода живёт только в окружении сервера и не известен никому лично. У каждого разработчика свой ключ для локальной работы, с небольшим потолком расхода. Подрядчику выдаётся отдельный ключ, который отзывается в день окончания работ.

Что ещё умеет ключ, кроме доступа

Ключ — это не только пропуск, но и точка, к которой привязаны настройки обращения.

Лимиты. Потолок расхода и допустимая частота запросов настраиваются на ключ, а не на аккаунт целиком.

Наблюдаемость. Расход в кабинете разбивается по ключам, поэтому разделение нагрузок даёт бесплатную аналитику: видно, сколько стоит каждый сценарий.

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

Из этого следует, что число ключей — не показатель бардака, а инструмент. Один ключ на всё выглядит аккуратно ровно до первого разбирательства, чей цикл съел месячный бюджет за ночь.

Что ключ говорит о счёте

С ключом связан баланс, и списание идёт за токены — единицы текста, на которые модель разбивает вход и выход. Это отличается от подписки: нет фиксированной суммы в месяц, есть расход, пропорциональный объёму.

Практически это значит, что бюджет считается умножением своего объёма на ставку модели. Обмен на 2 000 входных и 300 выходных токенов на ставке 8 ₽ за миллион стоит 0,0184 ₽, то есть 18,40 ₽ за тысячу обращений. На ставке 60 ₽ тот же обмен обойдётся в 0,138 ₽ и 138 ₽ за тысячу.

Как перевести своё потребление в токены и деньги — в статье как считать токены.

Частые ошибки вокруг ключа

Больше всего времени обычно съедает первая строка, и почти всегда причина механическая: при копировании ключа в конфиг попал перенос строки. Полный разбор кодов — в статье ошибки API нейросетей.

Что делать, если ключ утёк

Порядок действий, и он не терпит обсуждений.

Сначала отозвать ключ в кабинете — это одно действие и оно останавливает расход немедленно. Потом выпустить новый и подставить его в приложение. Потом посмотреть журнал за период с момента утечки и оценить, что успели сделать чужим ключом. И только потом разбираться, как он утёк.

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

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

Чего мы не утверждаем

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

Мы не утверждаем, что ротация ключей обязательна для всех: для личного пет-проекта она избыточна, для команды с текучкой — нет.

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

Что нужно, чтобы попробовать

Ключ заводится за минуту на keydealer.ru/login — почта и пароль, без документов и без зарубежной карты. Оплата российской картой в рублях, один ключ на весь каталог.

Платные текстовые модели доступны сразу на приветственном бонусе: сделать первый запрос и посмотреть, как выглядит расход, можно без пополнения. Как устроен первый вызов — в статье первый запрос к API нейросети.

Что держать в голове

Ключ — это пароль вашего кода, и ведёт он себя как пароль: утёк один раз, считается скомпрометированным навсегда.

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

При утечке сначала отзыв, потом расследование. Как мы проверяем факты и почему у каждой цифры стоит дата — на странице о проекте. Завести ключ: keydealer.ru/login.