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) з'являться окремими ендпоінтами в міру готовності. Таблиця вже описує фінальну модель прав, щоб інтеграції могли заздалегідь планувати, яке право знадобиться від власника ключа.

Що далі

Чи була стаття корисною?