API-ключи и секреты, объяснённые для новичка

Коротко

API-ключ, токен или строка подключения к базе — это секрет: кто его знает, тот действует от вашего имени и тратит ваши деньги. Правило одно: секрет никогда не пишется в код, конфиги или git — утёкший ключ боты находят в публичном репозитории за минуты, а ротация занимает минуту. Движок вшивает это структурно: в пакет попадают только плейсхолдеры вида ${GITHUB_MCP_PAT}, настоящие значения живут в переменных окружения на вашей машине (обычно .env, добавленный в .gitignore). Утёкший секрет считается скомпрометированным — его отзывают и создают новый, код менять не нужно. В статье — виды секретов, worked-пример подключения GitHub и пять привычек новичка.

Что это

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

• API-ключ / токен — длинная строка вроде sk_live_... или ghp_.... Кто её знает — тот действует от вашего имени.
• Строка подключения к БД (postgresql://user:пароль@host/db) — внутри спрятан пароль, поэтому вся строка — секрет.
• OAuth — вместо ключа вы разово логинитесь в браузере, и сервис сам выдаёт агенту временный доступ (часто безопаснее — постоянный ключ вообще не появляется).

Правило одно и простое: секрет — как ключ от квартиры. Не пишите его на двери. «Дверь» здесь — это ваш код, конфиги, логи, скриншоты и особенно то, что уходит в git.

Зачем так строго

Утёкший ключ = скомпрометированный ключ. Если ключ попал в закоммиченный файл, боты находят его в публичном репозитории за минуты и начинают тратить ваши деньги (инференс, облако) или читать ваши данные. Поэтому в движке есть жёсткий инвариант: «секрет никогда не попадает в файл значением; утёкший секрет считается скомпрометированным — ротируй». И этот принцип не просто написан в правилах — он вшит в то, как компилятор собирает пакет.

Плейсхолдер против значения — главная идея

Плейсхолдер — это имя-заготовка вида ${DATABASE_URI_RO} или ${GITHUB_MCP_PAT}. Оно говорит «сюда на твоей машине подставится настоящее значение», но самого значения не содержит. Движок раскладывает по пакету только плейсхолдеры. Настоящее значение вы кладёте отдельно — в переменные окружения на своём компьютере (обычно файл .env, который добавлен в .gitignore и никуда не уезжает).

Аналогия: пакет движка — это анкета, где написано «сюда впиши свой пароль», а не сам пароль. Анкету можно спокойно показать, переслать, закоммитить — пароля в ней нет.

Worked-пример: подключаем GitHub

Вход. Вы хотите, чтобы агент работал с вашими репозиториями, и включаете MCP-сервер github. Ему нужен персональный токен GitHub.

Что делает движок:

1. В спеке появляется запись в списке нужных секретов (secretsManifest) — только имя GITHUB_MCP_PAT и пометка «обязательный», плюс ссылка на доку, где токен создать.
2. При сборке в .mcp.json попадает заголовок с плейсхолдером, а не с токеном:

"headers": { "Authorization": "Bearer ${GITHUB_MCP_PAT}" }

3. В README и INSTALL движок выводит человекочитаемую строку: «GITHUB_MCP_PAT (обязательный) — Personal access token GitHub с нужными scopes (repo/read)». Значения — нигде.

Что делаете вы (один раз, у себя):

• Заходите в GitHub → Settings → создаёте токен с минимальными правами (например только repo:read, если агенту нужно лишь читать — это «принцип наименьших привилегий»).
• Кладёте его в своё окружение: export GITHUB_MCP_PAT=ghp_ваш_токен (или строкой в локальном .env).

Результат. Агент через ${GITHUB_MCP_PAT} подставляет ваш токен из окружения и работает с репозиториями. При этом в файлах, которые вы закоммитите или перешлёте, лежит только ${GITHUB_MCP_PAT} — сам токен физически не попал в артефакт. Если однажды токен всё же засветится — вы идёте в GitHub, отзываете старый, создаёте новый; менять код не нужно, плейсхолдер тот же.

Пять привычек новичка

1. Секрет — только в окружение/.env, не в код. И убедитесь, что .env в .gitignore.
2. Минимум прав. Нужен только просмотр — не давайте токен на запись/удаление.
3. Read-only, где можно. Для базы движок по умолчанию берёт read-only режим и отдельную роль — агент не сможет ничего испортить.
4. OAuth лучше вечного ключа. Многие пресеты (Vercel, Atlassian, Notion, Canva) авторизуются в браузере — постоянный ключ вообще не заводится.
5. Засветился — сразу ротируй. Отозвать и пересоздать — минутное дело; последствия слитого ключа — нет.

Честная граница

Пакет движка — обычные текстовые файлы у вас на диске: их можно открыть и прочитать, и это нормально — чужих секретов там нет, только ваши плейсхолдеры. Автоматическую проверку «секрет не утёк в диффе» перед сдачей движок предписывает как правило (secrets-hygiene, режим always); жёстко, кодом возврата, это блокируется пока только в Claude Code через hook, в остальных средах — как строгая инструкция.