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.

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

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

  • GET /org
  • GET /departments
  • GET /shift-presets
  • GET /status-types

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

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

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

Сейчас доступен один скоуп

На момент этой версии API в v1 подключён только employees.read (GET /employees) — остальные ресурсы из таблицы выше (schedule.read, checkins.read, timesheets.read, demand.read) появятся отдельными эндпоинтами по мере готовности. Таблица уже описывает финальную модель прав, чтобы интеграции могли заранее планировать, какое право потребуется от владельца ключа.

Что дальше

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