Аутентификация
Формат ключа, где его хранить, ограничения для отдельных ключей, ротация и что делать при утечке.
Каждый запрос к API несёт один API-ключ в заголовке Authorization:
Authorization: Bearer sk-popnow-3f9c0a…Других способов аутентификации нет: ключ в строке запроса URL никогда не принимается, а ваш вход на popnow.ai для API не действует.
Одно исключение: OpenAI-совместимые маршруты под /v1 читают ключ и из заголовка x-api-key, поэтому клиенты в стиле OpenAI работают без изменений. Нативные маршруты /api/v1 читают только Authorization.
Как выглядит ключ
Ключ — это sk-popnow- и 48 шестнадцатеричных символов в нижнем регистре. После создания API-консоль показывает только первые символы, поэтому потерянный ключ восстановить нельзя — просто создайте новый.
Создание ключа
- Войдите на popnow.ai и откройте API-консоль.
- Нажмите Create key и дайте ключу имя, по которому понятно, где он будет работать, например
production-backend. - Сразу скопируйте ключ. Он показывается один раз.
Ключей может быть несколько одновременно. Отдельный ключ для каждой среды или сервиса — хорошая привычка: тогда один можно отозвать, не трогая остальные. Все ключи расходуют один и тот же баланс кредитов.
Где хранить ключ
- В переменной окружения или хранилище секретов вашей платформы (
POPNOW_API_KEY), а не в исходном коде. - Никогда — в браузере, мобильном приложении или любом коде, который работает на чужом устройстве. Кто может прочитать ключ, тот может тратить ваши кредиты. Поставьте между ними свой сервер, и пусть PopNow вызывает он.
- Не в логах. Если вы логируете заголовки запросов, сначала уберите
Authorization.
Что разрешено ключу
Каждому ключу можно задать собственные ограничения в API-консоли:
| Ограничение | Что делает | Ошибка, когда срабатывает |
|---|---|---|
| Разрешённые модели | Ключ может вызывать только перечисленные модели | 40301 |
| Белый список IP | Запросы должны приходить с этих адресов или подсетей | 40302 |
| Лимиты расходов | Дневной, месячный и общий лимит для этого ключа, в кредитах | 40202 |
По умолчанию у ключа нет ни ограничений, ни лимитов. Ключам для продакшена давайте минимально необходимые права.
Задачи принадлежат ключу, который их создал
recordInfo, retry, purge, список задач и статистика видят только задачи, созданные тем же ключом. Задача, созданная другим ключом вашего аккаунта, отвечает 404 — так же, как несуществующая. Генерации, запущенные на сайте, не видны ни одному ключу. Чтобы увидеть весь аккаунт, используйте API-консоль.
Ротация
Как заменить ключ без простоя:
- Создайте новый ключ.
- Разверните его везде, где использовался старый.
- Убедитесь в консоли, что время последнего использования старого ключа больше не меняется.
- Отзовите старый ключ.
Если ключ утёк
- Отзовите его немедленно в API-консоли — это действует со следующего запроса.
- Создайте замену и разверните её.
- Проверьте, для чего его использовали: логи и статистика в консоли показывают каждую задачу, созданную этим ключом.
- Ограничьте новый ключ белым списком IP и лимитом расходов.
Если видите расходы, которые делали не вы, напишите в поддержку.
Как выглядит ошибка
Все три проблемы аутентификации возвращают HTTP 401 с code: 401, а различаются по msg:
Что говорит msg | Что произошло | Что делать |
|---|---|---|
| Нет учётных данных | Заголовок Authorization не дошёл | Проверьте, что заголовок задан и запущенный процесс видит переменную окружения |
| Формат ключа не распознан | Что-то пришло, но это не ключ PopNow | Убедитесь, что он начинается с sk-popnow-; возможно, вставлено что-то другое |
| Учётные данные недействительны или истекли | Ключа нет, он отозван или истёк | Создайте новый ключ; повтор никогда не сработает |
Действующий ключ тоже может получить 403 — например, если адрес почты аккаунта ещё не подтверждён (40310). См. Ошибки.