Організації та ролі

Ізоляція організацій визначає, які дані для того, хто звертається, взагалі існують. Ролі й рівні доступу ключів визначають, що він може з ними робити.

Організації та проєкти

Термін	Що це
Організація	Одиниця ізоляції даних. Усе, чим володіє клієнт, належить рівно одній організації.
Проєкт	Частина роботи організації. Ендпоінти, джерела та API-ключі належать проєкту.

Межа безпеки — це організація. Проєкт такою межею не є: він упорядковує роботу, але не обмежує, хто її бачить.

Записів іншої організації не існує

Кожен запит, який виконує API, сам шар даних обмежує організацією того, хто звертається, зокрема й пошук за ідентифікатором. Звідси два наслідки:

• Запит до ресурсу іншої організації за його ідентифікатором повертає 404, а не 403. Чужа організація і неправильний ідентифікатор виглядають однаково, тож ідентифікатор нічого не розкриває.
• Нова функція API отримує це обмеження автоматично.

Людина може бути учасником кількох організацій. POST /api/v1/auth/switch-organization видає токен доступу для іншої організації, де людина є учасником, з роллю, яку вона має в тій організації.

Ролі для людей

Роль	Що дозволяє
OWNER	Усе, зокрема керувати налаштуваннями організації та учасниками, експортувати дані й видаляти організацію
DEVELOPER	Переглядати й змінювати конфігурацію: ендпоінти, підписки, джерела, правила та все інше в проєкті
VIEWER	Лише переглядати

У списку ролей є й четверте значення, API_KEY, але цю роль нікому не призначають. Вона позначає запит, зроблений з API-ключем.

Що може лише власник

• Змінювати налаштування організації.
• Експортувати дані організації та видаляти її. Див. Зберігання та експорт даних.
• Додавати учасників, змінювати їхні ролі, видаляти, призупиняти й поновлювати учасників.

Кілька запобіжних перевірок не дають організації втратити доступ до самої себе. Кожна з них повертає 409 Conflict:

• Останнього власника, який ще може увійти, не можна понизити в ролі, видалити чи призупинити.
• Не можна призупинити самого себе.
• Роль OWNER не можна надати через запит на зміну ролі.

Рівні доступу для API-ключів

Рівень доступу	Що дозволяє
READ_WRITE	Читання й запис, зокрема надсилання подій
READ_ONLY	Лише читання

API-ключ ніколи не має прав OWNER, хоч би який у нього рівень доступу. Дії, дозволені лише власнику, завжди вимагають, щоб людина увійшла як власник.

Як перевіряється запит

Ролі й рівні доступу — різні види дозволів, тому кожна дія API вказує не мінімальну роль, а те, що їй потрібно від того, хто звертається:

Дії потрібно	Дозволено	Заборонено
Читання	Будь-кому після автентифікації	—
Запис	Власникам, розробникам, ключам READ_WRITE	Спостерігачам, ключам READ_ONLY
Права власника	Власникам	Усім іншим, зокрема будь-якому API-ключу

На відхилений запит API відповідає 403 зі стандартною структурою помилки. Див. Помилки та ліміти.

Чого поки немає

• Немає власних ролей і дозволів на окремі ресурси. Є лише три фіксовані ролі й два рівні доступу для ключів. Не можна дати комусь право запису в одному проєкті й лише читання в іншому в межах однієї організації.
• Немає SSO (SAML чи OIDC) і SCIM.
• Проєкти не обмежують доступ. Кожен учасник бачить усі проєкти організації з тією самою роллю.