Авторизация и общие правила

Каждый запрос несёт заголовок Authorization: Bearer <ключ>. Ключ показывается один раз при выпуске, у нас хранится только его хэш. Ключ тратит ваши деньги: храните его в переменной окружения, не в коде и не в логах, и вызывайте API только со своего сервера, а не из браузера или приложения пользователя.

Перевыпуск без простоя. В кабинете (раздел «Ключ и вебхук») при перевыпуске можно оставить прежний ключ рабочим ещё на 1, 24 или 72 часа: за это время замените его во всех скриптах. Без перекрытия прежний ключ гаснет сразу. Отозванный ключ отвечает 401 key_revoked, а не общим unauthorized.

Ключ только для чтения. Рядом с полным ключом можно выпустить второй, только для GET-запросов: списки, карточки подписок, баланс, операции, события. Покупки, продления и любые изменения он не делает (403 key_read_only). Удобен для дашбордов, аналитики и подрядчиков, которым незачем тратить депозит.

Привязка к адресам. В кабинете можно задать до 20 адресов и подсетей (203.0.113.7, 203.0.113.0/24, IPv6 тоже), с которых принимаются ключи. Запрос с другого адреса получит 403 ip_not_allowed, адрес будет в тексте ошибки. Список меняется только в кабинете: утёкший ключ не снимет ограничение сам.

Лимит: 60 запросов в минуту на ключ. Каждый ответ после проверки ключа, и успешный, и с ошибкой, несёт X-RateLimit-Limit (лимит), X-RateLimit-Remaining (сколько осталось в текущей минуте) и X-RateLimit-Reset (через сколько секунд освободится ближайший запрос). Превышение отвечает 429 с теми же заголовками и Retry-After.

Тело ответа всегда JSON. Успешный ответ содержит "success": true и данные. Отказ приходит с HTTP-статусом 4xx или 5xx и телом {"error": "текст", "error_code": "snake_case", "doc_url": "...", "request_id": "..."}: doc_url ведёт на разбор этого кода в главе «Ошибки», request_id это номер запроса.

У каждого ответа есть заголовок X-Request-ID. Пишите его в свои логи, а при обращении в поддержку называйте: по нему запрос находится за секунды. Можно прислать свой X-Request-ID в запросе, тогда ответ вернёт его же.

Даты приходят строкой ISO-8601 в UTC с суффиксом Z, например 2026-09-02T12:00:00Z. Исключение: first_seen и last_seen у устройств поставщик отдаёт со смещением +00:00, это тоже UTC.

Суммы приходят парой *_minor и *_usd, подробно в главе «Деньги».

Все пути начинаются с /api/v1/vpn. Новые поля в ответах добавляются без смены версии: не ломайтесь на незнакомых ключах. Удаление или переименование поля выйдет только под /v2 с предупреждением в кабинете.