> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Как безопасно управлять API-ключами?
> Систематическое руководство по безопасности API-ключей, охватывающее белые списки IP-адресов, белые списки моделей, лимиты расходов и то, как проверять утечку ключей
## Краткий ответ
Максимальная покупательная способность ключа определяется вашим **балансом аккаунта** — то есть если утечет любой один ключ, ваш наихудший возможный убыток будет равен всему, что осталось на вашем счете.
Защита ваших ключей сводится к четырем вещам: **выдавайте отдельные ключи для каждой цели, задавайте каждому ключу границу полномочий, ограничивайте сумму, которую может потратить один ключ, и не храните ключи там, где их может увидеть кто-то другой.**
**Самый часто упускаемый пункт**: если оставить на ключе включенную «Неограниченную квоту», этот один ключ откроет доступ ко всему балансу вашего аккаунта. Особенно для тестовых ключей всегда должен быть установлен лимит расходов.
## 1. Установите для token границу прав доступа
При создании token отметьте **«Включить расширенные параметры»**, чтобы показать настройки белого списка IP и доступных моделей.
### Белый список IP-адресов (рекомендуется для production)
Это **самая надежная защита из доступных**. После настройки только запросы с указанных IP-адресов смогут использовать token — даже если ключ утечет, с любого другого компьютера он бесполезен.
| Формат | Пример |
| ----------------- | -------------------------------------- |
| Один IP-адрес | `192.168.1.1` |
| Диапазон CIDR | `192.168.1.0/24` |
| Несколько адресов | Можно указать несколько записей вместе |
На production-серверах обычно фиксированный IP, поэтому они отлично подходят для белого списка IP. Укажите **публичный исходящий IP-адрес** вашего сервера, а не его внутренний адрес.
**Не включайте это для подключений с динамическим IP.** Домашний широкополосный доступ и офисные сети меняют исходящий IP, и каждый вызов будет завершаться ошибкой сразу после его изменения. Для таких сред используйте лимит расходов.
### Белый список доступных моделей (для выделенных tokens)
Если оставить поле "Доступные модели" **пустым, ограничений не будет** — token сможет вызывать любую model на платформе. После заполнения этого поля token сможет **только** использовать модели, которые вы указали.
У этого есть и плюсы, и минусы:
tokens для одной задачи: сервис, который только генерирует изображения, token, которым вы делитесь с внешним сотрудником, или изоляция бюджета по каждой модели.
Ежедневное личное использование и пробное тестирование. Вам придется возвращаться в консоль каждый раз, когда вы переключаете models, а несовпадающие псевдонимы model могут ломать вызовы.
В большинстве случаев мы **не рекомендуем** задавать доступные модели. См. [Нужно ли задавать доступные модели для token?](/ru/faq/token-model-whitelist) для полного анализа компромиссов.
## 2. Установите лимит расходов на токен
Это относится ко **всем**, и особенно к тестовым ключам.
При создании токена отключите «Неограниченная квота» и укажите сумму в поле «Авторизованная квота» — либо используйте один из пресетов ниже под полем (\$5 / \$20 / \$50 / \$100 / \$200 / \$500).
Смысл квоты в том, чтобы **ограничить ваши потери суммой, которую вы можете себе позволить**:
* Скомпрометированный ключ с квотой \$20 обойдется вам максимум в \$20
* Скомпрометированный ключ с включенной «Неограниченной квотой» может стоить вам **весь баланс аккаунта**
Максимальная сумма расходов по токену **ограничена балансом вашего аккаунта**. Квота \$500 не резервирует и не замораживает эти деньги — это лишь верхний предел расходов этого токена. Реально он все равно может потратить только то, что доступно на балансе.
## 3. Храните боевые и тестовые ключи раздельно
Никогда не используйте один ключ и для боевого трафика, и для локального тестирования. Когда они разделены, вы сможете полностью отключить проблемный test token, не затрагивая production.
| | Боевой ключ | Тестовый ключ |
| ------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
| **Список разрешенных IP** | Рекомендуется (IP сервера постоянный) | Обычно отключен (IP меняется) |
| **Разрешенная квота** | Оцените по трафику, оставьте запас | **Обязательно задайте**, рекомендуется \$5–\$50 |
| **Доступные модели** | Необязательно; зафиксируйте для стабильных нагрузок | Оставьте пустым для удобного переключения моделей |
| **Срок действия** | Можно настроить без срока действия | Укажите дату истечения |
| **Количество** | Один на проект или сервис | Один на тестовую задачу, отключайте после завершения |
Присваивайте tokens **понятные названия** в консоли (например, `prod-image-service`, `test-model-compare-0729`) вместо имен по умолчанию. Так вы гораздо быстрее найдете и отключите нужный token, когда что-то пойдет не так. См. [Tokens и группы](/ru/faq/token-and-groups).
## 4. Не храните ключи в этих местах
### Репозитории кода
Это безусловно самый распространенный путь утечки. Если ключ однажды попадает в Git, **он остается в истории коммитов даже после удаления файла**, и любой, у кого есть доступ к репозиторию, может его извлечь.
Вместо этого читайте их из переменных окружения:
```python theme={null}
import os
api_key = os.environ["APIYI_API_KEY"] # Correct
api_key = "sk-your-api-key" # Wrong: a real key hardcoded in source
```
Добавьте `.env` в `.gitignore` и **проверяйте перед коммитом**. Эта команда подходит для самопроверки:
```bash theme={null}
grep -rnE '(^|[^A-Za-z0-9])sk-[A-Za-z0-9]{10,}' .
```
Префикс `(^|[^A-Za-z0-9])` в этом шаблоне важен. Без него `sk-` внутри обычных слов вроде `task-`, `risk-` и `disk-` вызывает лавину ложных срабатываний, которая скрывает реальные результаты.
### Публичная документация, скриншоты и журналы
Перед публикацией документации или технического материала проверьте текст, примеры кода и **скриншоты**. Скриншоты консоли, записи терминала и журналы ошибок нередко содержат ключ целиком. Используйте заполнитель вроде `sk-your-api-key` в каждом примере.
**Публичные репозитории GitHub особенно опасны.** Они постоянно сканируются автоматическими ботами, и утекший ключ часто используется в течение нескольких минут. Прежде чем публиковать проект в open source, убедитесь, что ни код, ни история коммитов не содержат реальный ключ.
### Переписка с AI и AI-агентами
Этому пути утечки всего несколько лет, и его чаще всего недооценивают.
Вставка ключа в чат кажется временной мерой, но на практике:
Инструменты AI для программирования обычно хранят полный разговор на вашем компьютере в виде файлов обычного текста, сохраняют их бессрочно и никогда не очищают автоматически.
Возобновление старой сессии снова отправляет весь транскрипт как контекст, поэтому ключ не остается статичным.
Эти инструменты часто создают снимки файлов до и после изменений, поэтому скрипт с ключом оказывается скопирован несколько раз.
Эти файлы доступны для чтения **любой программе, запущенной от вашего имени** — это более слабая граница, чем у вашего репозитория кода.
**Всегда используйте одноразовый ключ для AI-инструментов и агентов**: создайте его отдельно, задайте ему небольшую квоту (например, \$5) и короткий срок действия, затем удалите его в консоли сразу после завершения задачи. Никогда не передавайте рабочий ключ AI-инструменту.
## Что делать, если ключ уже утек
Перейдите на [страницу token](https://api.apiyi.com/token) и удалите или отключите скомпрометированный token. Это единственное действие, которое немедленно прекращает утечку, и оно выполняется **до любого расследования**.
Выпустите новый token — на этот раз с лимитом расходов и любыми применимыми границами разрешений — и обновите конфигурацию приложения.
Просмотрите ваши [журналы вызовов](/ru/faq/call-logs) на предмет аномалий в период утечки: незнакомые модели, необычный объем или запросы в часы, когда вы не работали.
Выясните, где именно произошла утечка ключа — в коде, документации, скриншотах, транскриптах чата — и удалите это везде. Иначе ключ на замену утечет тем же способом.
## Частые вопросы
Скорее всего, указан неверный IP. Вам нужен **публичный исходящий IP** сервера, а не внутренний адрес вроде `192.168.x.x`.
Если вы вызываете из домашнего широкополосного подключения или офисной сети, исходящий IP меняется вместе с вашим ISP, и такие среды плохо подходят для IP whitelist — используйте вместо этого лимит расходов.
Чтобы устранить проблему, сначала очистите IP whitelist, убедитесь, что вызовы снова работают, а затем добавляйте правильные IP по одному.
Нет. Авторизованная квота — это только **потолок расходов** для этого token, а не предоплата и не блокировка средств.
Вы можете назначить пяти token по квоте \$100 каждому, имея на аккаунте только \$50 — они будут делить эти \$50, и когда они закончатся, ни один из token работать не будет. Максимальная расходная способность token всегда ограничена балансом аккаунта.
Ограничений нет; создавайте столько, сколько нужно.
Мы рекомендуем разделять их по схеме **проект плюс среда**, например `prod-support-bot`, `prod-image-service`, `test-model-eval`. Более гранулярные token позволяют отключить ровно один, не затрагивая ничего остального, а расходы и логи каждого token можно проверять независимо.
Нет. После исчерпания квоты вызовы отклоняются, но сам token сохраняется. Просто **отредактируйте token и увеличьте разрешенную квоту** в консоли, чтобы продолжить — не нужно создавать новый или обновлять конфигурацию.
Именно поэтому стоит задавать лимит расходов: это восстановимый ограничитель, а не необратимое удаление.
Проверьте логи вызовов. Самые важные три признака: **models, которые вы никогда не используете**, **вызовы вне рабочего времени** и **объем запросов, не соответствующий вашей нагрузке**.
См. [Как расследовать неожиданное использование ключа?](/ru/faq/troubleshoot-key-usage) для полной процедуры.
## Связанные документы
Полная справка по созданию, редактированию и группировке tokens.
Стоит ли задавать доступные модели и на что обратить внимание.
Используйте логи, чтобы определить реального инициатора неожиданных обращений.
Как APIYI шифрует трафик и защищает ваши данные на стороне платформы.
Безопасность никогда не бывает мелочью. Все настройки выше находятся на [странице управления token](https://api.apiyi.com/token) — нескольких минут настройки достаточно, чтобы закрыть большую часть риска.