SmengoAPI

Скоупы и права

Скоуп — это то, что конкретному API-ключу разрешено читать. Скоупы грубые (по ресурсу целиком, не по отдельному полю) и все без исключения — только для чтения: /api/v1 в v1 не пишет данные.

Жёсткий принцип

Скоуп открывает ровно те данные, которые пользователь-создатель ключа увидел бы сам в интерфейсе Smengo. API не даёт доступа к данным, скрытым от этого пользователя правами доступа — то есть скоупы ключа всегда являются подмножеством прав его создателя. Если сотрудник, создающий ключ, сам не видит табели — он не сможет выдать ключу timesheets.read, даже если попытается: это проверяется на сервере при создании ключа.

Таблица скоупов

Скоуп Право, которое требуется у создателя ключа Что открывает
employees.read «Управлять сотрудниками» GET /employees
schedule.read «Смотреть график» GET /schedule-entries
checkins.read «Управлять сотрудниками» GET /check-ins
timesheets.read «Табель» GET /timesheets
demand.read «Управление сменами» GET /demand-signals — включает данные о выручке

Право в правой колонке — то же самое, которое гейтит просмотр этих данных в самом приложении Smengo (раздел «Настройки → Роли»): если у пользователя нет доступа к разделу «Табель» в интерфейсе, он не сможет создать ключ со скоупом timesheets.read.

Обратите внимание: в строках табеля только employee_id, без имён — для типового отчёта «табель с именами сотрудников» ключу, помимо timesheets.read, нужен и employees.read.

Справочники без скоупа

Часть ресурсов не содержит секретов и доступна любому валидному ключу организации — независимо от набора скоупов:

Эти эндпоинты нужны, чтобы интерпретировать остальные данные (например, узнать название отдела по department_id из ответа /employees), поэтому они открыты без дополнительных условий.

Что происходит без нужного скоупа

Если у ключа нет скоупа, необходимого эндпоинту, — ответ 403 missing_scope. Какой именно скоуп нужен — в hint тела ошибки. Подробнее про формат ошибок — в Кодах ошибок.

Что дальше

Была ли статья полезна?