Партнёрский API
Серверный API для партнёров: выпуск ключа, чтение конфигурации витрины и локаций, создание клиентов, выдача тарифов и управление подписочными ссылками из своего сайта или телеграм-бота.
Партнёрский API позволяет создать свой сайт, личный кабинет или телеграм-бота поверх CreateYourVPN.
API охватывает клиентов, подписки, тарифы и конфигурацию витрины. Серверы, ноды, панели и SSH-данные находятся за пределами публичного контракта.
Только для интеграций между серверами. Храните API-ключ на своём сервере и не добавляйте его во frontend-код. Запросы с браузерными заголовками отклоняются с кодом 403 browser_forbidden.
Как получить ключ
Панель → меню аккаунта → Настройки → API и интеграции.
Дайте ключу название (телеграм-бот, лендинг) и включите только те права, которые ему нужны.
Нажмите Выпустить ключ и скопируйте значение целиком. Секрет показывается один раз, поскольку в сервисе хранится только его хеш.
Партнёр может иметь до 5 активных ключей. Для ротации выпустите новый ключ, обновите интеграцию и затем отзовите старый.
Аутентификация
Ключ передаётся как bearer-токен:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"X-API-Key: cyv_live_… тоже работает — на случай, когда Authorization занят прокси.
Ключ выглядит как cyv_live_<key_id>_<secret>. Первая половина (key_id) публична: именно её видно в панели, и её безопасно назвать поддержке. Вторая — секрет.
Права (scopes)
| Право | Что разрешает |
|---|---|
config:read | Читать конфигурацию витрины, тарифы, локации и /me. |
users:read | Читать клиентов, их подписки и трафик. |
users:write | Заводить клиентов, выдавать тарифы, сбрасывать ссылки, удалять клиентов. |
config:read достаточно для интеграций, которые только читают данные витрины. Добавляйте users:read или users:write только в том случае, если для интеграции необходимы соответствующие клиентские операции.
Контракт API и примеры
Полный исполняемый контракт находится в публичной коллекции Postman. В ней перечислены все методы, права, параметры, тела запросов, примеры ответов и стабильные коды ошибок. Коллекция генерируется из backend-контракта и содержит актуальные схемы запросов и ответов.
Лимиты
Лимит учитывается отдельно для каждого ключа и не зависит от IP-адреса запроса.
- 120 запросов в минуту на ключ в целом.
- 10 запросов в минуту отдельно на
GET /users.
Для GET /users действует отдельный лимит, поскольку каждый запрос загружает полный список клиентов. Для регулярных проверок используйте GET /users/{id} или поиск по externalId.
Рекомендуемая схема. Сохраните ID клиента CreateYourVPN из ответа на создание и используйте GET /users/{id} для последующих запросов. Свой идентификатор клиента можно связать с ним через externalId.
Идемпотентность
Три операции требуют заголовок Idempotency-Key: выдача тарифа, сброс подписочной ссылки и удаление клиента.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Повтор запроса с тем же ключом в течение 24 часов возвращает сохранённый ответ вместо повторного выполнения операции. Это предотвращает дублирование изменений после сетевого тайм-аута.
Создавайте отдельный ключ для каждого бизнес-события — например, платежа или действия — и используйте его во всех повторах этого события.
Если первая попытка ещё выполняется или её результат временно неизвестен, API возвращает 409 conflict без повторного выполнения операции. Перед следующим запросом проверьте текущее состояние клиента.
Актуальные схемы запросов и ответов находятся в публичной коллекции Postman выше.
Восстановление из копии
Два способа вернуть пользователей: восстановление в один клик прямо в панели (идемпотентный повторный импорт) или ручное восстановление в «чистый» Marzban, ведь файл — это нативный формат пользователей Marzban.
Аварийный доступ
Запасной способ подключиться, когда сеть использует белые списки и основное соединение заблокировано — создайте видеозвонок, передайте ссылку на него из кабинета или письмом и получите готовое подключение.