Коротко
Scope — это право API-ключа. При создании ключа вы выбираете, какие действия ему разрешены, и больше он ничего сделать не сможет. При вызове метода без нужного права придёт insufficient_scope (HTTP 403).
Всего есть шесть scope. Главный принцип простой: каждому ключу выдавайте только необходимое. Сайту, например, достаточно invoices:write и invoices:read — ни возвраты, ни подписки, ни управление вебхуками ему не нужны.
Шесть прав
| Scope | Что открывает |
|---|---|
invoices:read | Чтение счетов: список, один счёт, его события и возвраты |
invoices:write | Создание счетов, массовое создание, отмена |
refunds:write | Возврат денег |
subscriptions:manage | Создание и управление подписками |
webhooks:manage | Добавление, изменение и удаление адресов вебхуков |
partner:manage | Партнёрские методы: управление организациями клиентов |
Какое право открывает какой метод
| Метод | Нужное право | |||
|---|---|---|---|---|
GET /api/v1/invoices | invoices:read | |||
GET /api/v1/invoices/{id} | invoices:read | |||
POST /api/v1/invoices | invoices:write | |||
POST /api/v1/invoices/bulk | invoices:write | |||
POST /api/v1/invoices/{id}/cancel | invoices:write | |||
POST /api/v1/invoices/{id}/simulate | invoices:write (только песочница) | |||
POST /api/v1/invoices/{id}/refund | refunds:write | |||
GET /api/v1/subscriptions | subscriptions:manage | |||
POST /api/v1/subscriptions | subscriptions:manage | |||
PATCH /api/v1/subscriptions/{id} | subscriptions:manage | |||
POST /api/v1/subscriptions/{id}/pause \ | /resume \ | /cancel \ | /run | subscriptions:manage |
| Управление адресами вебхуков | webhooks:manage | |||
| Партнёрские методы | partner:manage | |||
GET /api/v1/status | Права не нужны |
Обратите внимание: возврат не входит в invoices:write. Это отдельное право refunds:write. Причина очевидна: выставить счёт и вернуть деньги — действия совершенно разного уровня риска.
Принцип минимальных прав
Не выдавать ключу лишнего — самая дешёвая и самая эффективная мера безопасности. Если ключ утечёт, посторонний сможет действовать только в пределах выданных прав.
Той части сайта, которая принимает заказы, хватает двух прав:
invoices:write — создать счёт по заказу
invoices:read — проверить, прошла ли оплатаКонкретные примеры:
| Интеграция | Достаточные права |
|---|---|
| Интернет-магазин, сайт | invoices:write, invoices:read |
| Telegram-бот | invoices:write, invoices:read |
| Система отчётности или аналитики | invoices:read |
| Панель оператора поддержки | invoices:read, refunds:write |
| Платформа с подписками | subscriptions:manage, invoices:read |
| Скрипт мониторинга или CI | ничего (/status открыт) |
| Партнёрская платформа | partner:manage и остальное по необходимости |
Обратный пример: коду сайта право refunds:write не нужно. Сайт никогда не возвращает деньги — возврат делается отдельным инструментом по решению человека. А при утечке разница огромная: в одном случае посторонний просто создаёт счета, в другом начинает возвращать деньги с вашего счёта Kaspi.
Ошибка insufficient_scope
{
"error": "insufficient_scope",
"message": "У ключа недостаточно прав для этого действия"
}HTTP-статус — 403. Эта ошибка не означает «ключ недействителен»: ключ верный, просто у него нет права на запрошенное действие.
У 403 есть и другие причины, не путайте их:
| Код | Что случилось |
|---|---|
insufficient_scope | У ключа нет нужного scope |
forbidden | Ресурс принадлежит другой организации |
tariff_inactive | Тариф неактивен или закончился пробный период |
account_blocked | Аккаунт заблокирован |
not_sandbox | Действие доступно только в песочнице |
А unauthorized (401) означает, что недействителен сам ключ — это совсем другая история. Порядок разбора: API отвечает 403.
Как добавить право ключу
Кабинет → Интеграции → API-ключи → откройте нужный ключ и измените права.
Важная деталь: менять ключ ради изменения прав не нужно. Сам ключ остаётся прежним, изменение вступает в силу сразу — ни переменную на сервере, ни код править не приходится.
Когда начинаете использовать новый метод, порядок обычный:
- Выпишите, какие методы вызывает ваш код.
- Найдите в таблице выше нужное право для каждого.
- Добавьте ключу только их.
- Проверьте в песочнице.
В обратную сторону так же: перестали использовать метод — уберите его право.
Права и привязка к кассиру — это разные вещи
Их часто путают:
| Scope | Привязка к кассиру | |
|---|---|---|
| Что ограничивает | Какое действие можно выполнить | Какие счета видны |
| Код ошибки | insufficient_scope (403) | invoice_not_found (404) |
| Пример | Не может сделать возврат | Не видит счёт другого кассира |
То есть, если у ключа есть refunds:write, но счёт принадлежит другому кассиру, возврат всё равно не пройдёт — только ошибка будет другая. Подробнее: API-ключи.
Чек-лист проверки
Перед выходом в прод пройдитесь по своим ключам:
- [ ] У каждой интеграции свой ключ
- [ ] У каждого ключа только нужные права
- [ ]
refunds:writeстоит действительно только там, где нужен - [ ]
partner:manageесть только у партнёрской платформы - [ ] Ни у одного ключа не включено «всё сразу, чтобы не думать»
- [ ] Старые неиспользуемые ключи удалены
Вопросы и ответы
Можно ли просто включить все права? Технически работать будет, но это многократно увеличивает ущерб от утечки ключа. Принцип минимальных прав — работа на одну минуту.
Если убрать право, старые счета пропадут? Нет. Scope влияет только на будущие запросы.
Разве invoices:write не покрывает возврат? Не покрывает. Для возврата нужен отдельный refunds:write: API возвратов.
Сколько прав нужно для подписок? Одно — subscriptions:manage. Для чтения выставленных подписками счетов пригодится ещё invoices:read: API подписок.
Действуют ли права в песочнице? Да, точно так же. Поэтому набор прав удобно обкатать сначала в песочнице.