Когда клиент присылает мне доступ к личному кабинету T‑Bank или OpenAI и спрашивает, что вообще с этим делать, я обычно начинаю с азов. Что такое API-ключ - это строка символов, которая подтверждает системе, что запрос к её API пришёл от конкретного приложения или пользователя, а не от случайного скрипта из интернета. По сути это пароль для программ, а не для людей: его не вводят в форму логина, а передают в заголовке запроса или в параметре, и по нему сервер понимает, кому отвечать и что этому клиенту разрешено.
Что такое API-ключ и зачем он нужен
API-ключ выдаёт сервис - платёжный шлюз, транспортная компания, языковая модель - когда вы регистрируете у него приложение или интеграцию. Дальше каждый запрос к API идёт с этим ключом, и сервер на той стороне решает: пропустить запрос, посчитать его в лимит тарифа, залогировать для биллинга или отклонить, если ключ просрочен или отозван.
Без ключа большинство современных API просто не отвечает - это защита от анонимных запросов и способ считать нагрузку по клиентам. Я делал интеграцию СДЭК для интернет-магазина на WooCommerce: без токена аккаунта СДЭК API отдаёт ошибку авторизации на любой запрос расчёта доставки, даже на самый простой - тариф и город получателя передать бесполезно, пока в заголовке нет валидного токена.
Ключ доступа к API, токен и секретный ключ - в чём разница
На практике термины путают, хотя разница есть и она важна для того, как ключ потом хранить и передавать.
| Тип | Где встречается | Срок жизни | Риск при утечке |
|---|---|---|---|
| Публичный ключ (public/client key) | Виджеты оплаты, SDK в браузере, карты Яндекс/Google | Обычно бессрочный, привязан к домену | Низкий - рассчитан на то, что виден в коде страницы |
| Секретный ключ (secret key) | Серверные вызовы: T‑Bank эквайринг, OpenAI, Claude API | До ручного отзыва | Высокий - прямой доступ к деньгам или лимитам аккаунта |
| OAuth-токен | Интеграции с Google, Telegram Login, CRM | От часа до нескольких месяцев, есть refresh-токен | Средний - ограничен правами (scope) и временем |
| Bot-токен (aiogram, Bot API) | Telegram-боты | Бессрочный до отзыва через BotFather | Высокий - полный контроль над ботом и его перепиской |
Секретный ключ API - это как раз тот случай, ради которого стоит городить отдельное хранилище и переменные окружения, а не как приятное дополнение к проекту. Публичный ключ можно спокойно светить в исходниках фронтенда, секретный - никогда.
Как ключ передаётся в запросе
Ключ может передаваться на сервер тремя основными способами, и от выбора способа зависит, насколько легко его случайно засветить в логах или в истории браузера. Через заголовок Authorization с типом Bearer - самый распространённый вариант для OpenAI, Anthropic и большинства современных REST API, заголовки не попадают в адресную строку и обычно не логируются прокси-серверами по умолчанию. Через query-параметр прямо в URL - так до сих пор работают некоторые старые API и часть виджетов карт, но такой ключ оседает в логах веб-сервера и в истории браузера, поэтому для секретных ключей способ подходит плохо. Через отдельное поле в теле запроса - вариант СДЭК и части банковских API, где токен передаётся вместе с остальными данными запроса в формате JSON.
Пример запроса к Claude API с ключом в заголовке - ключ подставляется через переменную окружения прямо в момент выполнения, а не хранится в теле скрипта:
curl -X POST https://api.anthropic.com/v1/messages
-H "x-api-key: $ANTHROPIC_API_KEY"
-H "content-type: application/json"
-d '{"model":"claude-sonnet-5","max_tokens":100}'
При такой записи в истории команд терминала сам ключ не остаётся видимым, если переменная объявлена в отдельном файле окружения, а не введена вручную в консоли.
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Где взять API-ключ на практике: T‑Bank, СДЭК, OpenAI, Tilda
Процедура получения почти везде одинаковая: регистрация юрлица или аккаунта разработчика в личном кабинете сервиса, создание приложения или магазина, генерация ключа в разделе интеграций или API. Разница в деталях.
- Для эквайринга T‑Bank ключ терминала и пароль магазина выдаются после подключения интернет-эквайринга через личный кабинет банка - я обычно сразу прошу клиента прислать их через защищённый канал, а не в мессенджере открытым текстом.
- СДЭК выдаёт токен по связке account/secure_password в разделе интеграции API, и токен там живёт ограниченное время - запрос на обновление нужно делать заново, это учитывается в логике интеграции.
- У OpenAI и Anthropic ключ генерируется в консоли разработчика один раз и показывается всего один раз - если не скопировали, придётся создавать новый и отзывать старый.
- В Tilda ключи внешних сервисов чаще всего прописывают в кастомных Zero Block скриптах - и вот здесь я регулярно вижу главную ошибку: секретный ключ платёжной системы или CRM зашит прямо в JS, который выполняется в браузере посетителя и виден через просмотр кода страницы.
У большинства сервисов ключ привязан не только к правам доступа, но и к тарифному лимиту запросов в минуту или в месяц - при интеграции Telegram-бота на aiogram с Claude API я всегда закладываю обработку ошибки превышения лимита отдельно от обработки ошибки неверного ключа, потому что клиенту важно понимать разницу: один случай значит закончились деньги на балансе, другой - ключ отозван или введён неправильно. Если сервис поддерживает несколько активных ключей одновременно, разумно завести отдельный ключ для теста и отдельный для продакшна, а не использовать один и тот же токен на двух окружениях - так в логах сразу видно, с какого окружения пришёл запрос.
Если у проекта уже есть похожая интеграция и нужен рабочий каркас, а не решение с нуля, у меня в разделе с готовыми скриптами лежат заготовки под СДЭК, эквайринг и Telegram-ботов - быстрее адаптировать под задачу, чем писать с чистого листа.
Как хранить секретный ключ API правильно
Базовое правило: ключ не должен лежать там, куда есть доступ у браузера, у публичного репозитория или у случайного человека с доступом к серверу без необходимости. На практике это выливается в несколько конкретных приёмов.
Переменные окружения вместо хардкода
В любом бэкенд-проекте - будь то Laravel API, aiogram-бот на Python или n8n-воркфлоу - ключ должен приходить из переменной окружения (файл .env, который не коммитится в git), а не быть строкой в коде:
import os
from aiogram import Bot
BOT_TOKEN = os.getenv("BOT_TOKEN")
CLAUDE_API_KEY = os.getenv("CLAUDE_API_KEY")
bot = Bot(token=BOT_TOKEN)
Секрет-менеджеры для боевых проектов
Для проектов с несколькими серверами или командой разработчиков переменных окружения в .env уже мало - файл всё равно лежит на диске сервера, и его теряют при миграции или случайно архивируют вместе с бэкапом. Vault, AWS Secrets Manager, Doppler или встроенное хранилище секретов в GitHub Actions решают эту проблему: ключ хранится зашифрованным, доступ к нему логируется, а ротация делается в одном месте, без пересборки кода.
| Способ хранения | Когда уместен | Основной риск |
|---|---|---|
| Хардкод в коде | Никогда, даже в MVP | Ключ попадает в git-историю навсегда, даже после удаления строки |
| .env на сервере, вне git | Небольшие проекты, один сервер | Теряется при неаккуратном бэкапе или переносе |
| Секреты CI/CD (GitHub Actions, GitLab CI) | Автоматический деплой | Нужно следить за правами участников репозитория |
| Vault / Secrets Manager | Продакшн с несколькими сервисами и командой | Требует настройки и отдельного администрирования |
Для n8n история отдельная: сами credentials он хранит зашифрованными в своей базе, но шифруются они значением переменной N8N_ENCRYPTION_KEY - если её потерять при переезде на новый сервер, расшифровать сохранённые ключи интеграций уже не получится, и все API-ключи в подключениях придётся вводить заново. Отдельно стоит сказать про данные клиентов, которые идут через такие интеграции: если бот или CRM-сценарий складывает контакты и переписку в облачную таблицу за рубежом, это уже вопрос требований 152-ФЗ о локализации персональных данных - такие данные логичнее вести на серверах в России, а не в первом попавшемся зарубежном сервисе.
Ошибки хранения API key, из-за которых утекают деньги
За несколько лет работы с интеграциями я видел один и тот же набор проблем на разных проектах.
- Ключ эквайринга или OpenAI API коммитят в публичный репозиторий на GitHub - боты сканируют такие репозитории постоянно, и рабочий ключ находят за минуты, а не за дни.
- Секретный ключ платёжного шлюза передают в письме или в общем чате Telegram, где состоит вся команда включая бывших подрядчиков.
- Один и тот же ключ используют одновременно на тестовом и боевом окружении - при утечке тестового стенда автоматически рискует и продакшн.
- Ключ не ограничивают правами: там, где сервис поддерживает scope или IP-ограничение, ставят токен с полным доступом ко всем операциям аккаунта вместо узкого набора прав под конкретную задачу.
Из этого списка утечка через git - самая частая причина, с которой ко мне обращаются: клиент присылает ключ T‑Bank, который уже год как публично виден в истории коммитов старого репозитория, потому что кто-то один раз закоммитил .env вместе с остальным кодом, а потом просто удалил файл в следующем коммите - в истории git он остался.
Ротация и отзыв ключей: как жить с длинным сроком жизни токена
Даже правильно спрятанный ключ рано или поздно стоит поменять - не потому что он испортился, а потому что уменьшается окно, в которое может сработать утечка, о которой вы ещё не знаете. Практика, которую я предлагаю клиентам:
- Ротация раз в 3-6 месяцев для ключей платёжных систем и AI-интеграций, даже если утечки не подозреваете.
- Немедленный отзыв ключа при уходе разработчика или подрядчика из команды, а не смена паролей потом при случае.
- Хранение даты создания и владельца ключа в отдельном закрытом реестре - когда ключей десяток на разные сервисы, без этого не вспомнить, какой за что отвечает и кому его выдавали.
- Тестирование отзыва ключа перед тем, как он реально понадобится: чтобы в момент инцидента не выяснилось, что кнопка отозвать в личном кабинете сервиса ведёт не туда, куда думали.
Если такую ротацию и хранение секретов настраивать руками на каждом проекте, уходит время, которое проще потратить на саму разработку. Я обычно закладываю базовую инфраструктуру для секретов сразу в момент интеграции - это входит в стоимость разработки под ключ и снимает вопрос, куда положить ключ, на будущее, а не оставляет его на потом.
Искусственный интеллект для бизнеса
AI / Claude API
от 50 000 ₽
Подробнее →Частые вопросы
Чем API-ключ отличается от пароля пользователя
Пароль подтверждает личность человека при входе в интерфейс, а API-ключ подтверждает право конкретного приложения обращаться к серверу без участия человека в моменте запроса. Пароль вводят один раз в форму, ключ передаётся программно с каждым запросом к API.
Можно ли хранить API-ключ в базе данных проекта
Можно, если база и таблица с ключами не доступны напрямую из интернета и данные в ней шифруются, а не лежат открытым текстом. Для большинства проектов проще и надёжнее переменные окружения или секрет-менеджер - в базе ключи хранят обычно только когда система сама выдаёт ключи множеству пользователей, например SaaS-платформа со своим API для клиентов.
Что делать, если API-ключ случайно попал в публичный репозиторий
Сразу отозвать ключ в личном кабинете сервиса и сгенерировать новый - удаление коммита из истории git саму утечку не отменяет, ключ уже мог быть просканирован. После отзыва проверить логи использования старого ключа на подозрительную активность за период, пока он был доступен публично.
Нужно ли отдельно ограничивать права API-ключа, если сервис это позволяет
Да, это стоит делать всегда, когда сервис поддерживает scope или ограничение по IP-адресу. Ключ с правом только на чтение данных о доставке не даёт злоумышленнику ничего интересного при утечке, а ключ с полным доступом к оплатам - прямой убыток.