Организации и пользователи

Организации и квоты, пользователи и роли, гранты доступа, смена пароля, эффективные права.

Раздел описывает управление арендаторами и доступом: организации с их квотами, учётные записи, роли, гранты (правила доступа к камерам) и теги, по которым эти гранты выдаются.

Во всех примерах используются переменные:

BASE=https://cctv.example.com
TOKEN=$(curl -sS -X POST "$BASE/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"login":"admin","password":"ВАШ-ПАРОЛЬ"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')

ORG_ID=<UUID>
USER_ID=<UUID>
TAG_ID=<UUID>

Общие соглашения — заголовки, коды ошибок, пагинация, вход и обновление сессии — в Введении и аутентификации. Те же операции через интерфейс описаны в разделах Организации, квоты и лимиты и Пользователи и права доступа.

Модель доступа#

Прежде чем создавать пользователей, разберитесь с тремя понятиями: роль, грант и эффективные права. Роль задаёт, что человек может администрировать; грант — что он может смотреть; эффективные права — результат вычисления гранта на конкретной камере.

Три роли#

Правила, которые система соблюдает жёстко:

• суперадминистратор существует только в организации по умолчанию;
• хотя бы один включённый суперадминистратор должен существовать всегда: последнего нельзя удалить, отключить или понизить в роли (409 {"error":"last_superadmin"});
• администратор организации не может ни создать суперадминистратора, ни изменить его (403 {"error":"superadmin_is_superadmin_only"}), ни выйти за пределы своей организации.

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

Что такое грант#

Грант — это пара «область + маска привилегий». Область отвечает на вопрос «на какие камеры», маска — «что с ними можно делать».

Маска привилегий — целое число, сумма битов:

Примеры: «живое видео + архив» — 1 + 2 = 3; «живое видео + архив + события + превью» — 1 + 2 + 4 + 32 = 39; все привилегии — 63. Допустимая маска — строго больше 0 и меньше 64.

Отдельно от грантов существуют ссылки для внешних получателей — временный доступ к одной камере без учётной записи; они описаны в разделе Доступ по ссылке.

Как считаются эффективные права#

У каждой камеры есть набор меток: идентификатор её организации плюс идентификаторы всех её тегов. Эффективная маска камеры для пользователя — побитовое ИЛИ всех масок, чьи метки совпали хотя бы с одной меткой камеры. Это объединение, а не пересечение: если один грант дал живое видео, а другой — архив, человек получит и то и другое.

Суперадминистратору доступ выдаётся универсальной маской 63 на всю установку, администратору организации — служебным грантом «вся своя организация, маска 63». Гранты в базе им не нужны.

Точно так же считает и нода, поэтому ответ GET /api/v1/users/{id}/effective показывает не приблизительную оценку, а то, что нода реально разрешит.

Пример: оператор с доступом «живое видео + архив» на один тег#

Полный сценарий из четырёх вызовов.

1. Создайте тег и пометьте им нужные камеры (пометка камеры — в разделе Настройка камер):

TAG_ID=$(curl -sS -X POST "$BASE/api/v1/tags" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Проходная","kind":"site"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')
echo "$TAG_ID"

2. Создайте оператора (роль user — значение по умолчанию):

USER_ID=$(curl -sS -X POST "$BASE/api/v1/users" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"login":"operator1","password":"ПАРОЛЬ-НЕ-МЕНЕЕ-8-СИМВОЛОВ","display_name":"Оператор смены"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

3. Выдайте грант «живое видео + архив» (1 + 2 = 3) на этот тег и ничего больше:

curl -sS -X PUT "$BASE/api/v1/users/$USER_ID/grants" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"base\":0,\"tags\":[{\"tag_id\":\"$TAG_ID\",\"privileges\":3}]}"
# {"base":0,"tags":[{"tag_id":"<UUID>","privileges":3}]}

"base": 0 означает «прав на организацию целиком не давать» — доступ будет только по тегу.

4. Проверьте результат:

curl -sS "$BASE/api/v1/users/$USER_ID/effective" -H "Authorization: Bearer $TOKEN"
# {"total_cameras":120,"live":8,"dvr":8,"events":0,"ptz":0,"export":0,"preview":0}

Читается так: в организации 120 камер, оператор видит живое видео и архив по 8 камерам с тегом «Проходная», и не имеет ни событий, ни PTZ, ни экспорта, ни превью. Если live равен нулю — скорее всего тегом не помечена ни одна камера.

Организации#

Организация — корень аренды: пользователи, камеры, теги, шаблоны, квоты и глубина хранения событий принадлежат ей. Все изменения организаций доступны только суперадминистратору; администратор организации может лишь прочитать карточку своей организации, чтобы видеть действующие квоты.

Во всех полях-лимитах значение null означает «без ограничения», а не ноль. Ноль означает «ничего нельзя». Отрицательные значения отклоняются.

GET /api/v1/orgs#

Суперадмин

Справочник организаций.

Параметры запроса

curl -sS "$BASE/api/v1/orgs?limit=50" -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Ответ — страница { "rows": [...], "next": "<UUID>|null" }. Поле next заполняется, только если страница пришла ровно на limit строк; когда оно null — записи кончились.

Ошибки: 400 {"error":"query_too_long"} (q длиннее 128 символов).

POST /api/v1/orgs#

Суперадмин

Создаёт организацию. В одной транзакции заводятся сама организация, её счётчики использования и первая ревизия политики хранения событий.

Тело запроса. Обязательно только name, остальное имеет значения по умолчанию.

curl -sS -X POST "$BASE/api/v1/orgs" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Филиал Север","max_cameras":200,"max_users":25,"event_retention_days":180}' \
  | python3 -m json.tool

Ответ — 201 с карточкой организации (см. следующий метод).

Ошибки

GET /api/v1/orgs/{id}#

Администратор — суперадмин видит любую организацию, админ организации только свою (иначе 403 cross_org).

Карточка организации вместе со счётчиками использования.

curl -sS "$BASE/api/v1/orgs/$ORG_ID" -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

{ "id": "<UUID>", "name": "Филиал Север", "disabled": false,
  "max_cameras": 200, "max_users": 25, "max_sessions_per_user": null,
  "max_dashboards": null, "max_reports": null, "max_tags": null,
  "max_event_templates": null, "max_agents": null, "max_agent_devices": null,
  "max_agent_access_rules": null, "attachment_quota_bytes": null,
  "event_retention_days": 180, "placement_mode": "manual",
  "allowed_node_ids": null, "allowed_storage_names": null,
  "deleting_at": null, "created_at": "2026-01-01T00:00:00Z",
  "usage": { "attachment_bytes": 0, "cameras_count": 12, "users_count": 3,
             "dashboards_count": 0, "reports_count": 0, "tags_count": 4,
             "event_templates_count": 0, "agents_count": 0, "agent_devices_count": 0,
             "agent_access_rules_count": 0, "events_count": 0, "attachments_count": 0 } }

Счётчики usage поддерживаются транзакционно и не пересчитываются при чтении, поэтому метод дёшев. Непустое deleting_at означает, что организация уже поставлена в очередь на удаление.

Ошибки: 403 {"error":"cross_org"}; 404 {"error":"not_found"}.

PATCH /api/v1/orgs/{id}#

Суперадмин — администратор организации не может править собственную организацию.

Частичное изменение: название, признак отключения, квоты, глубина хранения событий и политика размещения. Изменение выполняется под блокировкой строки, поэтому одновременные правки не теряют полей. Все поля необязательны, пропущенное поле остаётся прежним.

curl -sS -X PATCH "$BASE/api/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"max_cameras":300,"placement_mode":"auto","allowed_node_ids":null}'

Ошибки: те же коды 400, что при создании, плюс 404 not_found и 409 already_exists.

Изменение event_retention_days добавляет новую ревизию политики хранения — прошлые события продолжают жить по той политике, при которой были записаны.

GET /api/v1/orgs/{id}/deletion-preview#

Суперадмин

Показывает, что именно будет уничтожено при удалении организации. Ничего не меняет.

curl -sS "$BASE/api/v1/orgs/$ORG_ID/deletion-preview" -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

{ "org_id": "<UUID>", "name": "Филиал Север",
  "users": 3, "cameras": 12, "tags": 4, "event_templates": 0, "camera_templates": 1,
  "reports": 0, "dashboards": 0, "widgets": 0, "mosaics": 2, "module_tokens": 0,
  "agents": 0, "agent_devices": 0, "agent_endpoint_leases": 0, "agent_access_rules": 0,
  "events": 15230, "attachments": 412, "attachment_bytes": 918273645,
  "audit_rows": 8801, "linked_database_rows": 0,
  "dvr_files": 20418, "dvr_bytes": 4398046511104, "dvr_telemetry_stale": false }

Признак dvr_telemetry_stale: true означает, что цифры по архиву взяты из несвежей телеметрии нод — считайте dvr_files и dvr_bytes приблизительными.

Ошибки: 404 {"error":"not_found"}.

DELETE /api/v1/orgs/{id}#

Суперадмин

Ставит организацию в очередь на уничтожение. Это не мгновенный каскад: Plane делает снимок предпросмотра, немедленно замораживает организацию (disabled: true, проставляется deleting_at) и ставит долговременное задание, которое постепенно вычищает события, вложения и архив, и только затем удаляет саму запись.

JOB_ID=$(curl -sS -X DELETE "$BASE/api/v1/orgs/$ORG_ID" -H "Authorization: Bearer $TOKEN" \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "$BASE/api/v1/cleanup-jobs/$JOB_ID" -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Ответ — 202 с заданием: id, kind, org_id, state, preview (замороженные цифры), progress, created_at, finished_at, last_error.

Ошибки

POST /api/v1/orgs/{id}/dvr-purge/preview#

Суперадмин

Пробный прогон очистки архива: сколько камер, файлов и байт попадёт под выборку. Ничего не меняет.

Тело запроса. Все поля необязательны, поэтому {} — это «все камеры за всё время до текущего момента».

curl -sS -X POST "$BASE/api/v1/orgs/$ORG_ID/dvr-purge/preview" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"from":"2026-01-01T00:00:00Z","to":"2026-02-01T00:00:00Z"}' | python3 -m json.tool

{ "spec": { "camera_ids": [], "from": "2026-01-01T00:00:00Z", "to": "2026-02-01T00:00:00Z" },
  "preview": { "cameras": 12, "dvr_files": 3120, "dvr_bytes": 671088640000,
               "dvr_telemetry_stale": false, "range_size_exact": false } }

В ответе возвращается нормализованная выборка (spec) — с отброшенными дубликатами и приведённой верхней границей. Для последующего удаления отправляйте именно её, а не исходную.

Признак range_size_exact: true бывает только тогда, когда не заданы ни from, ни to. Для выборки с границами по времени цифры файлов и байт — это текущие итоги камер, то есть контекст, а не точная оценка.

Ошибки

POST /api/v1/orgs/{id}/dvr-purge#

Суперадмин

Ставит в очередь фактическое удаление архива по той же выборке. Plane делает свежий предпросмотр и запускает долговременное задание, которое удаляет записи на нодах-владельцах и в настроенной копии S3.

Тело запроса — то же, что у предпросмотра.

JOB_ID=$(curl -sS -X POST "$BASE/api/v1/orgs/$ORG_ID/dvr-purge" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"from":"2026-01-01T00:00:00Z","to":"2026-02-01T00:00:00Z"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

# опрос выполнения
curl -sS "$BASE/api/v1/cleanup-jobs/$JOB_ID" -H "Authorization: Bearer $TOKEN" \
  | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d["state"],d["finished_at"],d["last_error"])'

Ответ — 202 с заданием того же вида, что при удалении организации.

Ошибки: все ошибки предпросмотра, плюс:

Пользователи#

Учётная запись принадлежит одной организации. Логин — глобальная идентичность установки: он уникален по всей системе и после создания не меняется.

GET /api/v1/users#

Администратор — суперадмин видит все организации или сужает выборку через ?org=, админ организации закреплён за своей.

Список учётных записей. Поиск и фильтры выполняются в базе до ограничения по числу строк, поэтому искать можно по всей организации, а не по загруженной странице.

Параметры запроса

curl -sS "$BASE/api/v1/users?role=user&limit=100" -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

{ "rows": [ { "id": "<UUID>", "org_id": "<UUID>", "login": "operator1", "role": "user",
              "display_name": "Оператор смены", "locale": "ru", "disabled": false,
              "created_at": "2026-01-01T00:00:00Z", "last_login_at": null } ],
  "next": null }

Хеш пароля не входит ни в один ответ API.

Ошибки: 403 {"error":"cross_org"}; 403 {"error":"not_admin"}.

POST /api/v1/users#

Администратор — суперадмин может создать учётную запись в любой организации, админ организации только в своей.

Создаёт пользователя. Квота max_users проверяется под блокировкой счётчика, поэтому одновременные создания не могут её превысить.

Тело запроса

curl -sS -X POST "$BASE/api/v1/users" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"login":"operator1","password":"ПАРОЛЬ-НЕ-МЕНЕЕ-8-СИМВОЛОВ","role":"user","display_name":"Оператор смены"}' \
  | python3 -m json.tool

Ответ — 201 с карточкой пользователя.

Ошибки

GET /api/v1/users/{id}#

Любой вошедший — свою карточку читает любой; чужую только администратор в пределах своей организации.

curl -sS "$BASE/api/v1/users/$USER_ID" -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Ошибки: 403 {"error":"cross_org"}; 403 {"error":"superadmin_is_superadmin_only"}; 404 {"error":"not_found"}.

PATCH /api/v1/users/{id}#

Администратор — перевод в другую организацию доступен только суперадмину.

Частичное изменение. Все поля необязательны; пропущенное остаётся прежним. Поля login в теле нет — логин неизменяем.

curl -sS -X PATCH "$BASE/api/v1/users/$USER_ID" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"disabled":true}'

Ошибки

DELETE /api/v1/users/{id}#

Администратор — суперадминистратора может удалить только суперадмин.

Удаляет учётную запись вместе с её грантами и сессиями. Идентификаторы ещё живых сессий заносятся в публичный список отзыва до удаления, поэтому нода не сможет продолжать отдавать видео по уже выданному токену.

curl -sS -X DELETE "$BASE/api/v1/users/$USER_ID" -H "Authorization: Bearer $TOKEN"
# {"id":"<UUID>","deleted":true}

Ответ — 200 с телом (не 204).

Ошибки: 404 not_found; 403 cross_org; 403 superadmin_is_superadmin_only; 409 {"error":"last_superadmin"} — в том числе при удалении отключённого суперадминистратора, если он последний.

POST /api/v1/users/{id}/password#

Любой вошедший — свой пароль меняет любой, чужой только администратор в пределах своей организации.

Устанавливает пароль. Проверки прежнего пароля нет: метод одинаково обслуживает и самостоятельную смену, и сброс администратором.

Тело запроса: {"password": "<не менее 8 символов>"}.

curl -sS -X POST "$BASE/api/v1/users/$USER_ID/password" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"password":"НОВЫЙ-ПАРОЛЬ-8-ПЛЮС"}'
# {"id":"<UUID>","password":"updated"}

Ошибки: 400 {"error":"password_too_short"}; 404 not_found; 403 cross_org; 403 superadmin_is_superadmin_only.

GET /api/v1/users/{id}/grants#

Любой вошедший — свои гранты читает любой, чужие только администратор в пределах своей организации.

Возвращает сохранённый набор грантов: маску на всю организацию и маски по тегам.

curl -sS "$BASE/api/v1/users/$USER_ID/grants" -H "Authorization: Bearer $TOKEN"

{ "base": 0, "tags": [ { "tag_id": "<UUID>", "privileges": 3 } ] }

Значение base: 0 означает «гранта на организацию целиком нет», а не «привилегии не настроены».

Ошибки: 404 not_found; 403 cross_org; 403 superadmin_is_superadmin_only.

PUT /api/v1/users/{id}/grants#

Администратор — выдать грант самому себе нельзя.

Полностью заменяет набор грантов пользователя одной транзакцией. Это не слияние: всё, чего нет в теле запроса, удаляется. Тело {} очищает гранты полностью.

Тело запроса

Проверки выполняются в таком порядке: корректность каждой маски → tag_id не может быть идентификатором организации (это метка базового гранта) → запрет повторов tag_id → суммарно не более 128 строк → каждый тег должен существовать в организации этого пользователя.

curl -sS -X PUT "$BASE/api/v1/users/$USER_ID/grants" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"base\":0,\"tags\":[{\"tag_id\":\"$TAG_ID\",\"privileges\":3}]}"

Ответ — 200 с принятым набором (эхо запроса, а не повторное чтение из базы).

Ошибки

GET /api/v1/users/{id}/effective#

Любой вошедший — свои права смотрит любой, чужие только администратор в пределах своей организации.

Показывает, до скольких камер пользователь действительно дотягивается по каждой привилегии. Вычисляется ровно так же, как это делает нода при выдаче видео, поэтому цифрам можно верить.

curl -sS "$BASE/api/v1/users/$USER_ID/effective" -H "Authorization: Bearer $TOKEN"

{ "total_cameras": 120, "live": 8, "dvr": 8, "events": 0, "ptz": 0, "export": 0, "preview": 0 }

Поле total_cameras — размер пространства поиска: для суперадминистратора это все камеры установки, для остальных — камеры их организации.

Ошибки: 404 not_found; 403 cross_org; 403 superadmin_is_superadmin_only.

Пользуйтесь этим методом как проверкой после каждого изменения грантов — он отвечает на вопрос «человек уже видит то, что должен?» без входа под его учётной записью.

Теги#

Тег — единица, по которой выдаются гранты и собираются мозаики и отчёты. Его идентичность — UUID, поэтому переименование ничего не ломает: гранты, камеры и мозаики остаются связанными.

Виды тегов — plain, site, custom; они отличаются только оформлением в интерфейсе. Жёсткий предел — 1024 тега на организацию; организация может задать меньший max_tags, и тогда действует меньшее из двух значений.

GET /api/v1/tags#

Администратор — суперадмин по всем организациям или с ?org=, админ организации только по своей.

Параметры запроса: org (uuid), after (uuid), limit (по умолчанию 500, диапазон 1…500), q (подстрока в названии), kind (plain, site или custom; иное значение — 400 bad_kind).

curl -sS "$BASE/api/v1/tags?limit=100" -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

{ "rows": [ { "id": "<UUID>", "org_id": "<UUID>", "name": "Проходная",
              "kind": "site", "created_at": "2026-01-01T00:00:00Z" } ],
  "next": null }

Ошибки: 400 {"error":"bad_kind"}; 403 cross_org; 403 not_admin.

Отдельного метода чтения одного тега нет: GET /api/v1/tags/{id} вернёт 405. Найдите тег в списке — например, с параметром q.

POST /api/v1/tags#

Администратор — суперадмин может создать тег в любой организации.

Тело запроса

curl -sS -X POST "$BASE/api/v1/tags" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Проходная","kind":"site"}'

Ошибки: 400 name_empty; 400 bad_kind; 403 cross_org; 403 not_admin; 404 not_found (нет такой организации); 409 {"error":"organization_deleting"}; 409 {"error":"tag_limit"}; 409 {"error":"already_exists"}.

PATCH /api/v1/tags/{id}#

Администратор — перевод тега в другую организацию доступен только суперадмину.

Переименовывает тег, меняет его вид или переносит в другую организацию. Гранты, привязки камер и ссылки из мозаик переименование переживают без изменений.

Тело запроса: name, kind, org_id — все поля необязательны.

curl -sS -X PATCH "$BASE/api/v1/tags/$TAG_ID" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Проходная (север)"}'

Ошибки

DELETE /api/v1/tags/{id}#

Администратор — в пределах своей организации.

curl -sS -X DELETE "$BASE/api/v1/tags/$TAG_ID" -H "Authorization: Bearer $TOKEN"
# {"id":"<UUID>","deleted":true}

Ошибки: 404 not_found; 403 cross_org.

Сессии#

Вход и продление сессии описаны в Введении и аутентификации (POST /api/v1/auth/login и POST /api/v1/session/refresh). Здесь важно другое: какие действия из этого раздела обрывают чужие сессии.

Клиент отличает эти случаи по ответу продления сессии: 401 {"error":"evicted"} — «вас вытеснили или отозвали», 401 {"error":"unauthorized"} — «токен просто негоден». Продление сессии заново считывает роль и гранты, поэтому изменение прав доходит до нод не позже следующего продления.

Маршруты, которых нет#