Документация / API
Токены доступа
Ключи для скриптов и ботов: два набора прав, лимиты, отзыв.
Токен доступа нужен скриптам, ботам и панелям реселлеров, которые управляют вашими VPS через API. Пароль от аккаунта в скриптах не используется.
Создать токен
- Откройте в кабинете Настройки → Токены API → Новый токен.
- Дайте ему понятное название: где он используется.
- Выберите права: Только чтение: VPS и баланс или Управление VPS.
- Скопируйте токен. Мы показываем его один раз, а храним только отпечаток — восстановить токен нельзя, только выпустить новый.
Токен выглядит так: crp_ и ещё 43 символа. Для создания токенов нужна подтверждённая почта. Активных токенов может быть до 50.
Как передавать
curl -H "Authorization: Bearer crp_..." https://turtleguard.cloud/api/v1/cloud/vmsТокен работает только в заголовке Authorization. Не кладите его в адрес запроса: адреса попадают в журналы и историю браузера.
Что доступно токену
Токен работает только с VPS и балансом: методы /cloud/…, GET /billing/balance, GET /billing/transactions, а также GET /auth/me и GET /openapi.json. На любой другой адрес API ответит 403 с кодом auth.token_area. Домены, DNS и правила защиты токеном не управляются. Это касается и токенов, выпущенных раньше.
Права
| В панели | Права токена | Что можно |
|---|---|---|
| Только чтение: VPS и баланс | cloud:read, billing:read | Смотреть серверы, их нагрузку и снимки, баланс и операции |
| Управление VPS | cloud:read, cloud:write, billing:read | Всё то же, плюс заказывать, включать и выключать, переустанавливать, продлевать и удалять серверы, менять IP и тариф, открывать консоль |
Если токену не хватает прав на метод, API отвечает 403 с кодом auth.scope. Какие права нужны каждому методу, указано в списке методов.
Чтение — тоже доступ к серверам
Токен «Только чтение» видит данные серверов целиком, вместе с паролем root. Храните его так же бережно, как токен с управлением.
Выдавайте минимум
Витрине, которая только показывает клиентам состояние серверов, хватит «Только чтение». «Управление VPS» нужно тому, что заказывает и продлевает серверы. Делайте отдельный токен на каждую систему: тогда утечку одного можно закрыть, не трогая остальные.
Лимиты
На каждый токен — не больше 300 запросов в минуту, из них не больше 30, которые что-то меняют (всё, кроме GET). Сверх лимита API отвечает 429 с кодом rate_limited и заголовком Retry-After: через столько секунд можно повторить.
Безопасность аккаунта
- Токен не может менять настройки аккаунта: пароль, почту, вход по коду, сеансы. Создать, посмотреть или отозвать токены тоже можно только из кабинета.
- Смена пароля аккаунта отзывает все токены сразу. После неё выпустите новые и замените их в скриптах.
- Сотрудник поддержки, который вошёл в ваш аккаунт для помощи, не может создать токен.
Срок и отзыв
- Токены из кабинета бессрочные: действуют, пока вы их не отзовёте.
- В списке токенов видно, когда токен использовали последний раз.
- Кнопка Отозвать выключает токен сразу. Отзывайте токен, если он мог попасть к посторонним, и токены уволившихся сотрудников.