Ключи и права
Ключ аккаунта даёт полный доступ ко всему: и чтение подписчиков, и отправку сообщений, и удаление. Отдать такой ключ подрядчику или вставить в чужой сервис страшно, а отозвать его можно только вместе со своим.
Поэтому рядом с ним живут ключи с правами: у каждого свой набор разрешений, свой список ботов и свой срок жизни.
Настройки аккаунта → карточка «Ключи с правами». Там же их можно создать и отозвать мышкой.
Права
Право состоит из раздела и действия. Читающее право никогда не разрешает запись.
| Право | Что открывает |
|---|---|
account:read | аккаунт, тариф, расход, журнал вызовов |
subscribers:read | карточки, поиск, списки, переписка |
subscribers:write | создание, теги, переменные, блокировка, удаление |
messages:send | отправка сообщений и рассылки |
chains:write | запуск и остановка цепочек и блоков |
lists:read / lists:write | списки |
catalog:read / catalog:write | каталог товаров |
calendar:read / calendar:write | приложение-календарь и Google Календарь |
crm:read / crm:write | воронка, этапы, ответственные |
payments:read / payments:write | платежи и ссылки на оплату |
bots:read / bots:write | боты, цепочки, генерация, выгрузка |
stats:read | статистика |
files:write | загрузка файлов |
links:read / links:write | короткие ссылки |
hooks:read / hooks:write | подписки на события |
keys:read / keys:write | управление самими ключами |
proxy:use | запрос через зарубежный сервер |
Можно указать и раздел целиком — subscribers означает и чтение, и запись. Право * или пустой список прав — полный доступ.
Актуальный перечень отдаёт метод GET /key/scopes.
Создать ключ
POST /key/create
curl -X POST https://api.quescha.com/api/key/create \
-H "Authorization: КЛЮЧ_АККАУНТА" -H "Content-Type: application/json" \
-d '{
"name": "Сайт: приём заявок",
"scopes": ["lists:write", "messages:send"],
"bots": ["123456789"],
"days": 90
}'
| Поле | Обязательный | Описание |
|---|---|---|
name | Да | чтобы отличать ключи: «сайт», «1С», «n8n» |
scopes | Нет | массив прав; пусто — полный доступ |
bots | Нет | массив BotID: ключ увидит только эти боты |
days | Нет | срок жизни в днях; 0 — бессрочный |
rate | Нет | своя частота запросов в секунду |
{
"key": {
"id": 7,
"name": "Сайт: приём заявок",
"key": "1f9c04f0f0a3f1e4d2c0a9b8e7d6c5b4",
"scopes": ["lists:write", "messages:send"],
"bots": ["123456789"],
"active": true,
"expires": "2026-11-26T…"
}
}
Значение ключа целиком приходит только в ответе на создание. Дальше в списке видно лишь начало и конец: 1f9c…c5b4. Потеряли — отзовите и создайте новый.
Остальные методы
GET|POST /key/list — ключи аккаунта: права, боты, срок, сколько вызовов сделано, когда и с какого адреса использовался последний раз.
POST /key/edit — поменять название, права, список ботов, срок или выключить ключ (active: false).
POST /key/revoke — отозвать ключ навсегда. Работает сразу: следующий же запрос получит 401.
Что происходит при отказе
| Ситуация | Ответ |
|---|---|
| ключа нет в запросе | 401 unauthorized |
| ключ не найден | 401 unauthorized |
| ключ отозван | 401 key_revoked |
| срок ключа истёк | 401 key_expired |
| у ключа нет нужного права | 403 forbidden_scope |
| бот не в списке ключа | 404 no_bot — как будто такого бота нет |
Ключи с правами и старые методы
Методы первой очереди — каталог, календарь, прокси, баланс — написаны раньше и ищут ключ аккаунта сами. Чтобы ключи с правами работали и с ними, перед ними стоит прослойка: она проверяет право и подставляет обработчику ключ аккаунта.
Для вас это значит, что ключ с правами работает со всеми методами одинаково. Ключ аккаунта проходит насквозь, ничего не замечая, — существующие интеграции работают как работали.