SnapOtter/apps/docs/uk/guide/users-roles.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash, i18n_hash_version

description	i18n_source_hash	i18n_provenance	i18n_output_hash	i18n_hash_version
Керуйте користувачами, вбудованими та власними ролями, дозволами, ключами API, командами, сеансами й журналом аудиту в SnapOtter.	bea8955f3aff	human	802ed8983042	2

Користувачі, ролі та дозволи

SnapOtter постачається з трьома вбудованими ролями, 17 деталізованими дозволами та підтримкою власних ролей із необов'язковим контролем доступу на рівні окремих інструментів. Ця сторінка охоплює повну модель авторизації, обмеження області дії ключів API, керування командами та журналювання аудиту.

::: tip Пов'язані сторінки OIDC / SSO | SAML SSO | Провізіювання SCIM | Безпека та посилення захисту :::

Користувачі

Створення користувачів

Адміністратори можуть створювати користувачів через панель адміністратора або кінцеву точку POST /api/auth/register. Кожен користувач має ім'я користувача, роль, призначення до команди та необов'язкову адресу електронної пошти.

Типовий адміністратор

Під час першого запуску SnapOtter створює типовий обліковий запис адміністратора. Облікові дані беруться зі змінних середовища:

Змінна	Типове значення	Опис
DEFAULT_USERNAME	admin	Ім'я користувача для початкового облікового запису адміністратора
DEFAULT_PASSWORD	admin	Пароль для початкового облікового запису адміністратора

Типовий адміністратор зобов'язаний змінити свій пароль під час першого входу.

Провайдери автентифікації

Користувачі можуть автентифікуватися кількома способами:

• Локально - ім'я користувача та пароль, що зберігаються в базі даних SnapOtter
• OIDC - будь-який провайдер OpenID Connect (див. OIDC / SSO)
• SAML - постачальники ідентичності SAML 2.0 (див. SAML SSO)
• SCIM - автоматизоване провізіювання від постачальника ідентичності (див. Провізіювання SCIM)

Вимкнення автентифікації

Задайте AUTH_ENABLED=false, щоб повністю вимкнути автентифікацію. У цьому режимі для всіх запитів використовується синтетичний анонімний користувач із роллю admin. Вхід не потрібен.

::: warning Вимкнення автентифікації надає повний доступ адміністратора будь-кому, хто може дістатися екземпляра. Використовуйте це лише в довірених середовищах. :::

Вбудовані ролі

SnapOtter містить три вбудовані ролі. Їх не можна змінити чи видалити.

Admin

Усі 17 дозволів. Повний контроль над екземпляром.

tools:use files:own files:all apikeys:own apikeys:all pipelines:own pipelines:all settings:read settings:write users:manage teams:manage features:manage system:health audit:read compliance:manage webhooks:manage security:manage

Editor

7 дозволів. Може використовувати всі інструменти та керувати всіма файлами й конвеєрами, але не має доступу до адміністративних функцій.

tools:use files:own files:all apikeys:own pipelines:own pipelines:all settings:read

User

5 дозволів. Може використовувати інструменти та керувати власними ресурсами.

tools:use files:own apikeys:own pipelines:own settings:read

Довідник дозволів

Дозвіл	Опис
tools:use	Використовувати будь-який інструмент обробки
files:own	Переглядати власні файли та керувати ними
files:all	Переглядати файли всіх користувачів та керувати ними
apikeys:own	Створювати власні ключі API та керувати ними
apikeys:all	Переглядати ключі API всіх користувачів
pipelines:own	Створювати власні конвеєри та керувати ними
pipelines:all	Переглядати конвеєри всіх користувачів та керувати ними
settings:read	Переглядати налаштування екземпляра
settings:write	Змінювати налаштування екземпляра
users:manage	Створюйте облікові записи користувачів і керуйте ними в межах повноважень актора
teams:manage	Створювати, оновлювати та видаляти команди
features:manage	Встановлювати комплекти AI-функцій та керувати ними
system:health	Доступ до кінцевих точок стану та готовності
audit:read	Переглядати журнал аудиту та перелічувати ролі
compliance:manage	Керуйте життєвим циклом GDPR і функціями відповідності; деструктивні операції користувача залишаються обмеженими повноваженнями
webhooks:manage	Налаштовувати вихідні вебхуки
security:manage	Керувати налаштуваннями безпеки (список дозволених IP, примусове застосування SSO)

Власні ролі

Адміністратори з дозволом security:manage можуть створювати власні ролі через панель адміністратора або API ролей. Перелічення ролей потребує audit:read.

Створення власної ролі

curl -X POST http://localhost:1349/api/v1/roles \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reviewer",
    "description": "Can use tools and view all files",
    "permissions": ["tools:use", "files:own", "files:all", "settings:read"]
  }'

Назви ролей мають бути 2-30 символів, малими літерами, буквено-цифровими, з дефісами й підкресленнями.

Межі делегованого адміністрування

Усі 17 дозволів можна делегувати за допомогою спеціальних ролей, але адміністративний дозвіл не робить цю роль еквівалентною вбудованій ролі admin. Мутації користувача, дозволені users:manage, деструктивні операції, дозволені compliance:manage, і керування нестандартними ролями, дозволені security:manage, обмежені поточними повноваженнями актора:

• Вбудовані ролі слідують за admin > editor > user; настроювані ролі знаходяться нижче вбудованих ролей.
• Дозволи цілі повинні міститися в ефективних дозволах актора. Таким чином, ключ API із обмеженою областю не може використовувати дозволи, випущені з його області.
• Доступ до інструментів цільової ролі має бути обмежений власним доступом до інструментів актора.
• Вимкнений обліковий запис перевіряється на його початкову роль, якщо ця роль записана як disabled:<original-role>.
• Для видалення настроюваної ролі також потрібні повноваження для призначення вбудованого резервного варіанта user; недієздатні учасники залишаються недієздатними як disabled:user.

Глобальні облікові дані та конфігурація суворіші: для видачі або відкликання маркера SCIM та імпорту конфігурації екземпляра потрібна вбудована роль admin із повними ефективними повноваженнями адміністратора.

Дозволи на рівні інструментів

Власні ролі можуть за бажанням обмежувати, до яких інструментів мають доступ користувачі. Доступні два режими:

Режим	Поведінка	Вимога до ліцензії
category	Обмеження за модальністю (image, video, audio, document, file)	Немає (безкоштовно)
tool	Обмеження за ID окремого інструмента	Потребує корпоративної функції per_tool_permissions

Коли задано режим tool, але корпоративна функція недоступна, SnapOtter коректно деградує та дозволяє доступ до всіх інструментів.

{
  "name": "image-only",
  "permissions": ["tools:use", "files:own"],
  "toolPermissions": {
    "mode": "category",
    "allowed": ["image"]
  }
}

Видалення власної ролі

Коли власну роль видаляють, усіх призначених до неї користувачів автоматично переназначають на роль user.

Команди

Команди групують користувачів для керування сховищем і збереженням. Команда Default створюється під час першого запуску.

Поле	Тип	Опис
name	string	Унікальна назва команди (1-50 символів)
storageQuota	number	Обмеження сховища для команди в байтах (працює без корпоративної ліцензії)
retentionHours	number	Автовидалення результатів після стількох годин (потребує team_retention_overrides, корпоративна)
legalHold	boolean	Запобігати автоматичному видаленню файлів учасників команди (потребує legal_hold, корпоративна)

::: info Команду Default не можна видалити. Команди, у яких досі є учасники, видалити не можна. Спершу переназначте учасників. :::

Ключі API

Користувачі можуть генерувати ключі API для програмного доступу. Кожен ключ використовує префікс si_ і показується лише один раз під час створення.

Дозволи з обмеженою областю дії

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

curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline key",
    "permissions": ["tools:use", "files:own"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Термін дії

Ключі приймають необов'язкову позначку часу expiresAt. Ключі з простроченим терміном дії відхиляються під час автентифікації.

Журнал аудиту

SnapOtter записує події, важливі для безпеки, у структурований журнал аудиту, що зберігається в таблиці бази даних audit_log.

Перегляд журналу аудиту

GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z

Потребує дозволу audit:read. Підтримує пагінацію (page, limit) та фільтри (action, ip, from, to).

Аудит операцій з інструментами

::: warning Події TOOL_EXECUTED не журналюються за замовчуванням. Вони вмикаються за вибором через один із двох шляхів:

1. Задайте адміністративне налаштування auditToolOperations у true.
2. Майте активну ліцензію з функцією audit_export (доступна як у планах team, так і enterprise).

Без одного з цих варіантів окремі виконання інструментів не записуються в журнал аудиту. :::

Експорт

GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z

Потребує дозволу audit:read та корпоративної функції audit_export (доступна як у планах team, так і enterprise). Підтримує формати CSV та JSON, фільтровані за action, actorId, targetType, targetId, from та to.

Підписування, стійке до підробки

Коли ввімкнено, кожен запис журналу аудиту підписується за допомогою HMAC, похідного від DATA_ENCRYPTION_KEY. Це потребує:

1. Задання DATA_ENCRYPTION_KEY у вашому середовищі.
2. Увімкнення адміністративного налаштування tamperResistantAudit.
3. Корпоративної ліцензії з функцією tamper_resistant_audit.

Збереження

Задайте AUDIT_RETENTION_DAYS, щоб автоматично очищати старі записи. Типове значення - 0, що означає, що записи зберігаються безстроково.

Довідник подій

Подія	Категорія
LOGIN_SUCCESS, LOGIN_FAILED	Автентифікація
OIDC_LOGIN_SUCCESS, OIDC_LOGIN_FAILED	Автентифікація
SAML_LOGIN_SUCCESS, SAML_LOGIN_FAILED	Автентифікація
LOGOUT	Автентифікація
USER_CREATED, USER_UPDATED, USER_DELETED	Керування користувачами
PASSWORD_CHANGED, PASSWORD_RESET	Керування користувачами
MFA_ENROLLED, MFA_DISABLED, MFA_VERIFIED, MFA_VERIFY_FAILED	MFA
MFA_CHALLENGE_ISSUED, MFA_RECOVERY_USED, MFA_RESET	MFA
ROLE_CREATED, ROLE_UPDATED, ROLE_DELETED	Ролі
API_KEY_CREATED, API_KEY_DELETED	Ключі API
SETTINGS_UPDATED, IP_ALLOWLIST_UPDATED	Налаштування
FILE_UPLOADED, FILE_DELETED	Файли
TOOL_EXECUTED	Інструменти (за вибором)
SCIM_USER_PROVISIONED, SCIM_USER_UPDATED, SCIM_USER_DEPROVISIONED	SCIM
SCIM_GROUP_SYNCED	SCIM
LEGAL_HOLD_APPLIED, LEGAL_HOLD_RELEASED	Відповідність
GDPR_EXPORT_INITIATED, GDPR_USER_PURGED, GDPR_TEAM_PURGED	Відповідність
CONFIG_EXPORTED, CONFIG_IMPORTED	Конфігурація

Керування сеансами

Сеанси базуються на кукі та керуються SESSION_DURATION_HOURS (типово: 168 годин / 7 днів).

Зміна ролі анулює сеанси

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

Запобіжники безпеки

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