API-ключ

Ключ передают в заголовке каждого запроса к API. По нему сервис понимает, чей это аккаунт и что программе разрешено.

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

Почти у каждого API есть ограничение на количество запросов в минуту на ключ — это тот самый rate limit.

В Prokso ключи создаются в кабинете («Настройки» → «API»), до 5 ключей, и показываются один раз. Лимит — 60 запросов в минуту на ключ. Описание методов — на странице API.

Что можно делать с ключом Prokso

• читать баланс, цены и список планов с остатком трафика;
• получать строки прокси для плана — такие же, как в генераторе в личном кабинете;
• добавлять и убирать адреса в доступе по IP (белом списке) плана;
• ставить план на паузу, возобновлять и переименовывать его;
• покупать новый план или докупать гигабайты к существующему — только с баланса.

API тратит только деньги, которые уже есть на балансе: пополнение делается в личном кабинете.

Как передавать и хранить ключ

Ключ передают в заголовке Authorization: Bearer YOUR_API_KEY или в X-API-Key. Все адреса начинаются с /api/v1, например запрос к /api/v1/me возвращает данные аккаунта и баланс. Держите ключ в переменной окружения, скажем PROKSO_KEY, а не в самом коде. Не вставляйте его в адрес запроса или во фронтенд сайта: там он попадет в журналы и в код страницы.

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

Как уложиться в 60 запросов в минуту

Сверх лимита API отвечает 429 с заголовком Retry-After: подождите указанное количество секунд и повторите запрос. Не опрашивайте баланс или список планов каждую секунду — для мониторинга достаточно раза в несколько минут.

Для покупок отправляйте заголовок Idempotency-Key с уникальным значением. Если соединение оборвется и вы повторите запрос с тем же ключом, покупка не задвоится. Все методы с примерами — на странице API.