Перейти к содержанию

Согласование изменений

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

По умолчанию согласование выключено. Владелец включает его для каждого действия отдельно.

Какие действия

Действие Что покрывает operation в запросе
Управление пользователями приглашение пользователя или добавление существующего, создание API-пользователя, удаление пользователя и API-пользователя, смена роли, блокировка и разблокировка пользователя (уже заблокированного или уже разблокированного — ответ сразу, без запроса) create, api_user_create, delete, role_change, block, unblock
Управление группами создание, переименование и удаление группы, состав участников create, update, delete, add_members, remove_members
Управление согласованием настройки кворума: порог администраторов, администраторы кворума и правила согласования, включая их выключение settings; при QUORUM_SETTINGS_STATE_DISABLED — threshold, admins, action_setting
Добавление адреса в белый список новый адрес во внешнем кошельке нет
Управление тегами создание, изменение и удаление тега, привязка и отвязка тегов к аккаунтам create, update, delete, attach_detach
Переводы на one-time адреса разрешение и запрет переводов по адресу вне белого списка нет
Управление политиками изменение правил политики и откат к версии из истории update, rollback

Согласование добавления адреса в белый список, тегов, переводов на one-time адреса и политик включается на стороне платформы: до включения правило для этих действий сохраняется, а изменение применяется сразу.

Правило одно на действие: нельзя требовать согласования удаления, но не смены роли. Изменения администратора платформы (PLATFORM_ADMIN) согласования не требуют. Поддержка платформы (PLATFORM_SUPPORT) не приглашает и не удаляет пользователей рабочего пространства и не меняет им роль: ответ 403 FORBIDDEN при любом состоянии согласования.

Кто подтверждает

Режим Значение mode Кто подтверждает
Владелец QUORUM_APPROVAL_MODE_OWNER_ONLY владелец рабочего пространства
Кворум администраторов QUORUM_APPROVAL_MODE_ADMIN_QUORUM администраторы кворума, назначенные владельцем; порог общий для всех действий в этом режиме
Группа QUORUM_APPROVAL_MODE_SPECIFIC_GROUP участники выбранной группы, чьей роли доступно мобильное приложение (все роли, кроме наблюдателя и оператора; API-пользователи входят в состав, но подтвердить не могут), со своим порогом

К кворуму администраторов или группе можно добавить обязательное подтверждение владельца.

Группу, выбранную в правиле, даже выключенном, меняют только владелец и администратор платформы: её название, описание, состав и роли её участников.

Изменение группы, выбранной в правиле Ответ
изменить группу или роль её участника — администратором 403 GROUP_PROTECTED_BY_QUORUM_SETTINGS; запрос на согласование не создаётся
удалить группу, даже если правило выключено GROUP_REFERENCED_BY_QUORUM_SETTINGS; сначала переведите правило в другой режим

Подтверждение принимается только с привязанного устройства в мобильном приложении. Инициатор тоже подтверждает свой запрос, владелец в режиме «Владелец» подтверждает сам.

Право подтверждать теряют, когда:

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

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

Заблокировать рабочее пространство нельзя

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

Администраторы кворума

В режиме «Кворум администраторов» подтверждают администраторы, которых назначил владелец: список входит в версию настроек, а при QUORUM_SETTINGS_STATE_DISABLED его задаёт PUT …/quorum/admins. Назначить можно пользователя с ролью администратора, в том числе неподписывающего; API-пользователя — нельзя. Роль проверяется только у добавляемых: уже назначенный остаётся в списке и без неё.

Что произошло Назначение Подтверждает
владелец назначил администратора есть да, пока вправе подтверждать
пользователю выдали роль администратора нет нет, пока владелец его не назначит
назначенного заблокировали, перевели на роль не администратора, отвязали последнее устройство остаётся нет; снова подтверждает, когда вернёт право
назначенного удалили из рабочего пространства снимается нет

Настройки под подписью владельца

Если настройки кворума подписывает владелец (signature.state не QUORUM_SETTINGS_STATE_DISABLED), порог администраторов, правила всех действий и администраторы кворума меняются только целиком, новой версией. В версию входит и состав групп, выбранных в правилах, на момент отправки.

Версия вступает в силу, когда владелец подтвердит запрос на неё в Pert Mobile: подтверждение подписывает версию ключом его устройства.

...............Pert........Владелецили администраторКонсольPertВладелец(Pert Mobile)Владелецили администраторКонсольPertВладелец(Pert Mobile)изменить настройкиотпечаток новой версииPUT …/quorum/settings403 QUORUM_APPROVAL_REQUIREDномер версии, snapshot_hash, отпечатокномер версии и отпечатокpush, запрос в очередиотпечаток по настройкам из запросавладелец сверяет номер версии и отпечатокподтвердить: одобрение версии,подписанное ключом устройстваверсия применяетсяEXECUTED
...............Pert........Владелецили администраторКонсольPertВладелец(Pert Mobile)Владелецили администраторКонсольPertВладелец(Pert Mobile)изменить настройкиотпечаток новой версииPUT …/quorum/settings403 QUORUM_APPROVAL_REQUIREDномер версии, snapshot_hash, отпечатокномер версии и отпечатокpush, запрос в очередиотпечаток по настройкам из запросавладелец сверяет номер версии и отпечатокподтвердить: одобрение версии,подписанное ключом устройстваверсия применяетсяEXECUTED

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

Новую версию отправляет «Управление согласованием» выключено (по умолчанию) Включено
владелец запрос на подпись, владелец подтверждает сам то же
администратор, включая неподписывающего, до первой подписанной версии не принимается: QUORUM_SETTINGS_NOT_SIGNED то же
администратор после первой подписанной версии не принимается: QUORUM_CHANGE_REQUESTS_DISABLED запрос на подпись владельцу
signature.state Что действует Новая версия
QUORUM_SETTINGS_STATE_UNINITIALIZED новое рабочее пространство без версий: правила по умолчанию из GET …/quorum/actions первую версию отправляет владелец, base_version — 0
QUORUM_SETTINGS_STATE_LEGACY прежние настройки рабочего пространства, созданного до подписи настроек владельцем первую версию отправляет владелец, base_version — 0; до неё настройки не меняются
QUORUM_SETTINGS_STATE_SIGNED последняя подписанная версия от последней версии: base_version — signature.version
QUORUM_SETTINGS_STATE_UNSPECIFIED состояние не прочитать: запись о последней версии повреждена, signature.mismatch — head не принимается: QUORUM_SETTINGS_UNVERIFIED, обратитесь в поддержку
QUORUM_SETTINGS_STATE_DISABLED настройки без подписи владельцем не принимается: настройки меняются по одной — владелец при выключенном «Управлении согласованием» сразу, иначе запросом, который подтверждает сам; администратор — запросом владельцу, пока «Управление согласованием» включено

Участников групп добавляют и убирают в группах, а не версией настроек. Новых подтверждающих добавляет только подписанная версия:

После подписи версии Подтверждает
пользователя добавили в группу, выбранную в правиле нет, пока владелец не подпишет версию, в которую он вошёл
участника убрали из группы или он потерял право подтверждать нет — сразу, без новой версии

Настройки расходятся с подписанной версией

Порог или правила, изменённые в обход подписи, и подписанная версия, которая не проходит проверку, останавливают согласование:

Что Ответ
действия из таблицы «Какие действия», кроме «Управления согласованием», даже с выключенным правилом, и голоса по их запросам 409 QUORUM_SETTINGS_UNVERIFIED
действия, согласование которых платформа ещё не включила применяются сразу
отмена чужого запроса администратором кворума по admins_can_cancel не принимается
новая версия настроек и голос по ней принимаются

Восстанавливает владелец новой версией:

Поле signature.snapshot есть Версий ещё не было: QUORUM_SETTINGS_STATE_UNINITIALIZED, signature.mismatch — unsigned_rows
base_version signature.version 0
admin_quorum_threshold из signature.snapshot из signature.current
rules по одному на действие из GET …/quorum/actions: из signature.snapshot, а у действия, которого там нет, — из signature.current из signature.current
groups как в Новой версии настроек то же
admins те из signature.snapshot, кто есть и в signature.current из signature.current

Если signature.snapshot нет у QUORUM_SETTINGS_STATE_SIGNED или новую версию не принимает тот же код, обратитесь в поддержку.

Как проходит согласование

.........Pert..............ИнициаторPertПодтверждающие(мобильное приложение)ИнициаторPertПодтверждающие(мобильное приложение)действие, например удаление пользователя403 QUORUM_APPROVAL_REQUIRED+ идентификатор запросаpush-уведомление,запрос в очереди согласованияподтвердить или отклонить(с привязанного устройства)alt[подтверждений достаточно]изменение применяетсяEXECUTED, либо FAILED с причиной[отказ, после которого порог не набрать]REJECTED[срок вышел]EXPIRED[запрос отменили]отменаCANCELLED
.........Pert..............ИнициаторPertПодтверждающие(мобильное приложение)ИнициаторPertПодтверждающие(мобильное приложение)действие, например удаление пользователя403 QUORUM_APPROVAL_REQUIRED+ идентификатор запросаpush-уведомление,запрос в очереди согласованияподтвердить или отклонить(с привязанного устройства)alt[подтверждений достаточно]изменение применяетсяEXECUTED, либо FAILED с причиной[отказ, после которого порог не набрать]REJECTED[срок вышел]EXPIRED[запрос отменили]отменаCANCELLED
  1. Инициатор выполняет действие как обычно. Если для него включено согласование, изменение не применяется, а ответ приходит с кодом QUORUM_APPROVAL_REQUIRED и идентификатором запроса.
  2. Тем, кто подтверждает, приходит push-уведомление на привязанное устройство. Они подтверждают или отклоняют запрос в мобильном приложении.
  3. Когда подтверждений достаточно, изменение проверяется заново и применяется само. Повторять действие не нужно.
  4. Отказ, после которого порог уже не набрать, закрывает запрос. Пока запрос ждёт голосов, его можно отменить. Запрос без нужных голосов истекает (EXPIRED).

Состав подтверждающих фиксируется при создании запроса и может только сокращаться. Кто потерял право подтверждать — выбывший — исключается из запроса при ближайшем голосе, повторной отправке того же изменения или другом изменении того же объекта (см. Одно изменение объекта за раз).

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

Запрос устаревает, если после создания у правила согласования изменились условие одобрения или порог либо после исключения выбывших порог уже не набрать. Устаревший запрос отменяется при первом голосе, повторной попытке того же изменения или другом изменении того же объекта; повторная попытка создаёт новый запрос.

Пока запрос не устарел и ждёт голосов, то же изменение от любого пользователя рабочего пространства возвращает этот же запрос (тот же approval_request_uuid). Инициатором остаётся создавший его: второй отправитель может отменить запрос только как владелец или администратор кворума (см. Отмена).

Статус Значение
PENDING ждёт подтверждений
APPROVED подтверждений достаточно, изменение применяется
EXECUTED изменение применено, в том числе когда применять уже нечего: правка тега, one-time адреса, блокировка заблокированного, разблокировка разблокированного — EXECUTED без изменений; привязка и отвязка тегов — FAILED, если не применилась ни одна операция
FAILED подтверждено, но применить нельзя; причина — в execution_error (её код — в execution_error_code): инициатор заблокирован, удалён или потерял права, в том числе на группу, которую выбрали в правиле после запроса; пользователь уже в роли или группе; адрес уже в белом списке; рабочее пространство заморожено; тег отвязан; тег или политика изменились после запроса; новая версия настроек, порог или список администраторов кворума не проходит тех же проверок, что при отправке (см. Администраторы кворума); запрос на изменение одной настройки создан при QUORUM_SETTINGS_STATE_DISABLED, а одобрен, когда настройки уже подписывает владелец
REJECTED отклонено
EXPIRED 72 часа прошли без нужных подтверждений
CANCELLED отменено до решения: инициатором, владельцем или администратором кворума, выключением согласования «Управления согласованием» (запросы на изменение настроек) или потому, что запрос устарел

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

Просмотр изменений в мобильном приложении

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

Если изменение большое, карточка показывает краткую сводку и кнопку «Посмотреть изменения». Кнопка открывает экран изменений с полным описанием «было → стало», добавленными и удалёнными значениями и пояснениями.

Подтверждают и отклоняют запрос в карточке: с экрана изменений вернитесь назад. У большого изменения кнопка «Подтвердить» доступна только после того, как экран изменений показал описание, — до этого под сроком запроса стоит подсказка «Чтобы подтвердить, откройте изменения»; отклонить можно сразу.

Состояние Что показано
Описание изменения ещё не загрузилось сводка и кнопка «Посмотреть изменения»; «Подтвердить» — как у большого изменения
Описание изменения требует новой версии мобильного приложения сводка, плашка «Обновите приложение, чтобы увидеть изменение целиком» и основные данные изменения; кнопки просмотра нет, «Подтвердить» доступна сразу
В изменении есть ослабление контроля (например, снятие запрета) или предупреждение плашка в карточке: у большого изменения «Есть важные изменения: откройте их перед решением», у небольшого — «Есть важные изменения: проверьте их перед решением» над ним
Описания изменения нет основные данные изменения в карточке, без «было → стало»
Описание изменения урезано плашка «Показано не всё: описание урезано по размеру» на экране изменений
При открытии экрана изменений запрос уже не ждёт подтверждений или не найден плашка «Запрос больше не ожидает решения»; описание, если оно есть, показано

Одно изменение объекта за раз

Пока по объекту есть запрос в работе — он ждёт подтверждений или подтверждён и применяется (не дольше 15 минут после подтверждения), — другое изменение того же объекта не принимается: ответ CHANGE_REQUEST_IN_PROGRESS с данными этого запроса.

Объект Что считается его изменением
политика транзакций обновление правил и откат к версии из истории
настройки кворума новая версия; при QUORUM_SETTINGS_STATE_DISABLED — по отдельности правило действия, порог кворума администраторов и список администраторов кворума
пользователь смена роли, блокировка, разблокировка, удаление
группа изменение, удаление, добавление и удаление участников
тег изменение и удаление; привязка и отвязка тегов объект не держат
one-time адреса рабочего пространства разрешение и запрет
Изменение объекта, пока по нему есть запрос в работе Ответ
другое изменение — и требующее согласования, и не требующее его сейчас CHANGE_REQUEST_IN_PROGRESS
другое изменение, если запрос в работе устарел или его срок вышел запрос закрывается (CANCELLED или EXPIRED), изменение идёт как при свободном объекте: запросом или сразу
то же самое изменение, пока согласование включено и запрос ждёт подтверждений как при регистрации: QUORUM_APPROVAL_REQUIRED с этим запросом
изменение администратора платформы (PLATFORM_ADMIN) принимается, запрос остаётся в работе

Чтобы изменить объект по-другому, запрос в работе нужно закрыть: дождаться решения или срока либо отменить его.

Отмена

Кто Что может отменить
инициатор свой запрос
владелец, пока сам вправе подтверждать любой запрос рабочего пространства, который ждёт подтверждений
администраторы кворума, пока сами вправе подтверждать запрос действия, в правиле которого включено admins_can_cancel

admins_can_cancel по умолчанию выключено; у правила «Управление согласованием» его включить нельзя. Запрос о себе самом — о своей блокировке, удалении или смене роли — администратор кворума отменить не может. Подтверждения с устройства отмена не требует.

Для интеграции

Ответ на действие, которому нужно согласование (текст error у каждого действия свой, опознавайте ответ по code):

{
  "error": "…",
  "code": "QUORUM_APPROVAL_REQUIRED",
  "details": {
    "approval_request_uuid": "3f0c5c1e-…",
    "action": "<action_key>",
    "operation": "delete",
    "mode": "QUORUM_APPROVAL_MODE_OWNER_ONLY",
    "expires_at": "2026-09-17T10:00:00Z"
  }
}

Ответ на изменение объекта, по которому есть запрос в работе:

{
  "error": "another change request for this object is in progress",
  "code": "CHANGE_REQUEST_IN_PROGRESS",
  "details": {
    "approval_request_uuid": "3f0c5c1e-…",
    "action": "<action_key>",
    "operation": "update",
    "status": "PENDING",
    "initiator_uuid": "7d1e…",
    "initiator": { "user_uuid": "7d1e…", "user_type": "user", "email": "anna@example.com", "first_name": "Anna" },
    "initiated_by_me": false,
    "can_cancel": true,
    "created_at": "2026-10-05T10:00:00Z",
    "expires_at": "2026-10-08T10:00:00Z"
  }
}
Поле details Когда есть
approval_request_uuid, action, status, initiated_by_me, created_at всегда
operation у действий с operation в таблице «Какие действия»
expires_at у запроса в PENDING
initiator_uuid, initiator только если вызывающему доступна карточка запроса — он участник запроса или у него VIEW_CHANGE_APPROVALS; initiator может отсутствовать и у них
can_cancel может отсутствовать

Ключ действия отдаёт GET …/quorum/actions полем key, в ответе на действие он приходит полем action. Режим передаётся значением из таблицы режимов: в ответе на действие, в запросах согласования и в настройках; исключение — base и target в payload запроса на версию настроек, см. Новая версия настроек.

Ответ действия Когда
403 QUORUM_APPROVAL_REQUIRED правило включено; запрос зарегистрирован, его данные — в details
409 QUORUM_NO_ELIGIBLE_APPROVERS правило включено, но подтверждать сейчас некому; изменение не сохраняется
409 CHANGE_REQUEST_IN_PROGRESS по объекту изменения уже есть запрос в работе, см. Одно изменение объекта за раз; изменение не сохраняется, в details — этот запрос
409 CHANGE_REQUEST_ALREADY_FINALIZED такой же запрос только что закрылся; изменение не сохраняется, повторите действие. У управления политиками код в теле — INTERNAL_ERROR при том же статусе
409 QUORUM_SETTINGS_UNVERIFIED настройки кворума расходятся с подписанной версией, см. Настройки под подписью владельца; изменение не сохраняется
503 CHANGE_APPROVAL_UNAVAILABLE проверить, нужно ли согласование, сейчас нельзя; изменение не сохраняется, повторите позже. У белого списка, тегов и one-time адресов тот же сбой может прийти как 500 INTERNAL_ERROR
Метод Путь Право
GET /api/v2/admin/tenants/{tenant_uuid}/change-approvals?scope=PENDING_MY_VOTE\|INITIATED_BY_ME\|ALL пользователь рабочего пространства; ALL — VIEW_CHANGE_APPROVALS; с привязанного устройства — только PENDING_MY_VOTE и INITIATED_BY_ME пользователя, привязавшего устройство к этому рабочему пространству
GET /api/v2/admin/change-approvals?scope=… — тот же список сразу по всем рабочим пространствам, доступным токену; страница общая как у списка рабочего пространства, по каждому пространству отдельно; ALL — только пространства с VIEW_CHANGE_APPROVALS, ни одного — 403
GET …/change-approvals/{request_uuid} участник запроса или VIEW_CHANGE_APPROVALS; с устройства — участник
POST …/change-approvals/{request_uuid}/approve, …/reject подтверждающий этого запроса (входит в sets[]), с привязанного устройства
POST …/change-approvals/{request_uuid}/cancel инициатор запроса, владелец и, если правило действия это разрешает (admins_can_cancel), администраторы кворума, см. Отмена; с привязанного устройства — пользователь, привязавший его к этому рабочему пространству
GET /api/v2/admin/tenants/{tenant_uuid}/quorum VIEW_QUORUM_SETTINGS
GET …/quorum/actions — список действий: ключ key (он же {action_key} в пути PUT) и fixed_mode — режим, заданный платформой; QUORUM_APPROVAL_MODE_UNSPECIFIED — режим выбирает владелец VIEW_QUORUM_SETTINGS
PUT …/quorum/settings — новая версия настроек MANAGE_QUORUM_SETTINGS; PROPOSE_QUORUM_SETTINGS — пока включено «Управление согласованием», после первой подписанной версии
PUT …/quorum/actions/{action_key}, …/quorum/threshold, …/quorum/admins — по одной, только при QUORUM_SETTINGS_STATE_DISABLED MANAGE_QUORUM_SETTINGS; PROPOSE_QUORUM_SETTINGS — только запросом, пока включено «Управление согласованием»
GET …/quorum/gated-actions — действия рабочего пространства и requires_approval: потребует ли действие у вызывающего согласования; права на настройки не нужны пользователь или API-пользователь с активной ролью в рабочем пространстве; с устройства — 403

Параметры списков: scope (по умолчанию PENDING_MY_VOTE), statuses (можно несколько: PENDING, APPROVED, REJECTED, EXPIRED, EXECUTED, FAILED, CANCELLED), action, limit (по умолчанию 50, не больше 200), offset; сортировка — новые первыми.

Устройству, привязанному в нескольких рабочих пространствах, хватает одного запроса: у каждого элемента списка своё пространство в tenant_uuid и tenant_name, а initiated_by_me считается по пользователю, привязавшему устройство к этому пространству. Карточка и голос — по путям пространства элемента.

Голос подписывается ключом привязанного устройства, который открывается биометрией или ключом безопасности. В теле approve и reject приложение передаёт signed_vote — JSON голоса в base64 — и signature, подпись Ed25519 этих байтов, тоже в base64:

{"type": "change_vote", "tenant_uuid": "…", "request_uuid": "3f0c5c1e-…",
 "vote": "approve", "device_uuid": "…", "changes_hash": "9f2c…"}

changes_hash — отпечаток описания из карточки, по которой голосуют, пусто без описания. Голос approve засчитывается, только если он совпадает с changes_hash запроса; reject — при любом.

Голос approve по новой версии настроек (operation — settings) подписывает другое сообщение — одобрение версии; reject — обычный change_vote:

{"type": "quorum_settings_approval", "tenant_uuid": "…", "request_uuid": "3f0c5c1e-…",
 "device_uuid": "…", "version": 4, "prev_hash": "3712b95f…", "snapshot_hash": "5d41…"}
Поле одобрения Значение
version payload.version запроса
snapshot_hash SHA-256 канонической записи payload.target, hex в нижнем регистре; приложение считает его само, платформа сравнивает со своим расчётом
prev_hash то же для payload.base, если payload.base_version больше 0, иначе пустая строка
tenant_uuid, request_uuid, device_uuid как в обычном голосе; других полей нет — сообщение не по формату получает 400
GET /api/v2/admin/change-approvals?scope=PENDING_MY_VOTE&limit=50
{
  "items": [
    { "request_uuid": "3f0c5c1e-…", "tenant_uuid": "0f8b7a5e-…", "tenant_name": "Treasury",
      "action": "<action_key>", "action_display_name": "Manage users", "status": "PENDING", "initiated_by_me": false },
    { "request_uuid": "a91d07b2-…", "tenant_uuid": "7c2e41d9-…", "tenant_name": "Trading",
      "action": "<action_key>", "action_display_name": "Manage tags", "status": "PENDING", "initiated_by_me": true }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Ответ на принятый голос и на отмену — обновлённая карточка запроса. Отмена переводит в CANCELLED запрос, открытые sets[] и неподанные голоса, поданные голоса остаются; кто и почему отменил — в cancelled_by и cancel_reason.

POST /api/v2/admin/tenants/{tenant_uuid}/change-approvals/3f0c5c1e-…/cancel
{
  "request": {
    "request_uuid": "3f0c5c1e-…",
    "status": "CANCELLED",
    "cancel_reason": "owner",
    "cancelled_by": { "user_uuid": "5b2f…", "user_type": "user", "email": "boss@example.com" },
    "sets": [
      { "external_id": "OWNER", "threshold": 1, "status": "CANCELLED",
        "approvers": [ { "user_uuid": "5b2f…", "status": "CANCELLED", "is_me": false } ] }
    ]
  }
}
Ответ На что Когда
CHANGE_VOTE_DEVICE_REQUIRED approve, reject голос не с привязанного устройства
CHANGE_VOTE_SIGNATURE_REQUIRED approve, reject голос не подписан ключом устройства, а approve по новой версии настроек — без одобрения версии: версия приложения устарела, его нужно обновить
CHANGE_VOTE_SIGNATURE_INVALID approve, reject голос подписан не ключом этого устройства или подписан другой голос; у approve — и подписанный changes_hash не совпадает с запросом, одобрение версии без подписи, не о версии запроса или прислано на запрос, который не меняет настройки
CHANGE_VOTE_NOT_ALLOWED approve, reject голосующий не входит в состав подтверждающих запроса или исключён из него, потеряв право подтверждать
QUORUM_SETTINGS_UNVERIFIED approve, reject настройки расходятся с подписанной версией, см. Настройки под подписью владельца; голос по новой версии настроек принимается
CHANGE_VOTE_CONFLICT approve, reject противоположный голос уже подан; повтор того же голоса по запросу, который ещё ждёт голосов, ничего не меняет
CHANGE_REQUEST_CANCEL_NOT_ALLOWED cancel нет права отменить запрос, см. Отмена
200, та же карточка cancel запрос уже отменён
CHANGE_REQUEST_ALREADY_FINALIZED все три запрос уже закрыт или истёк, в том числе при повторе решающего голоса; на голос — и когда запрос устарел: у правила согласования изменились условие одобрения или порог либо состав изменился так, что порог уже не набрать. Запрос при этом отменяется
CHANGE_REQUEST_NOT_FOUND все три запроса нет в рабочем пространстве; то же у карточки

Карточка запроса несёт всё, что нужно показать человеку, без дополнительных запросов:

{
  "request": {
    "request_uuid": "3f0c5c1e-…",
    "tenant_uuid": "…",
    "tenant_name": "Treasury",
    "action": "<action_key>",
    "action_display_name": "Manage users",
    "initiator": { "user_uuid": "7d1e…", "user_type": "user", "email": "owner@example.com", "first_name": "Anna", "last_name": "Smirnova", "api_user_name": "" },
    "initiated_by_me": false,
    "can_cancel": true,
    "cancel_reason": "",
    "payload": { "operation": "delete", "tenant_uuid": "…", "user_uuid": "9a4c…" },
    "display": { "user": { "user_uuid": "9a4c…", "user_type": "user", "email": "ivan@example.com", "first_name": "Ivan" }, "current_role": "EDITOR" },
    "status": "PENDING",
    "execution_error": "",
    "execution_error_code": "",
    "expires_at": "2026-10-08T10:00:00Z",
    "created_at": "2026-10-05T10:00:00Z",
    "updated_at": "2026-10-05T10:00:00Z",
    "summary": {},
    "changes_hash": "",
    "entities": {},
    "sets": [
      {
        "external_id": "OWNER",
        "threshold": 1,
        "status": "PENDING",
        "approvers": [ { "user_uuid": "5b2f…", "status": "PENDING", "user": { "user_uuid": "5b2f…", "user_type": "user", "email": "boss@example.com", "first_name": "", "last_name": "", "api_user_name": "" }, "is_me": true } ]
      }
    ]
  }
}
Поле Что содержит
initiator, sets[].approvers[].user участник: user_type — user или api_user; у пользователя email, first_name, last_name, у API-пользователя api_user_name
initiated_by_me, sets[].approvers[].is_me этот участник — вы; с привязанного устройства — пользователь, привязавший его к этому рабочему пространству
can_cancel вы можете отменить запрос сейчас, см. Отмена; есть и в списке
cancel_reason почему запрос в CANCELLED: initiator, owner, admin — отменил человек; rule_changed, approvers_changed — запрос устарел; change_requests_disabled — выключено «Управление согласованием». Пусто у запросов, отменённых раньше, чем появилось поле
cancelled_by кто отменил, участник, как initiator; поля нет, если запрос устарел или отменён раньше, чем появилось поле
execution_error причина отказа при FAILED, текст; есть и в списке; у остальных статусов — пустая строка
execution_error_code код этой причины из справочника ошибок, см. таблицу ниже; есть и в списке; у остальных статусов — пустая строка
expires_at, created_at, updated_at срок, время создания и последнего изменения запроса, RFC 3339
payload что будет изменено
display названия и имена того, на что ссылается payload, на момент создания запроса; поля нет, если снимка нет
summary однострочная сводка изменения по локалям шаблона, en есть всегда; есть и в списке; пусто, если описания изменения нет
changes описание изменения «было → стало» на момент создания запроса; в карточке и ответах на голос и отмену; поля нет, если описания нет
changes_hash отпечаток changes: меняется вместе с ним; клиент его не вычисляет, а только сравнивает; есть и в списке, пусто без описания
entities пользователи, сервисные аккаунты и группы из changes — свежие на момент ответа: ключ "<kind>:<id>" (kind — user, service_account, user_group), значение — name, subtitle (email), subtype (user или api_user), is_me, missing; там же, где changes, иначе пустой объект
Запрос в FAILED execution_error_code
«Управление пользователями», «Управление группами», «Управление согласованием» код причины; у причины без собственного кода — INTERNAL_ERROR
остальные действия, отказ из-за инициатора: заблокирован, удалён, потерял права FORBIDDEN
остальные действия, любой другой отказ пустая строка, причина — только в execution_error
закрыт раньше, чем появилось поле пустая строка
Действие operation Поля display
Управление пользователями role_change, delete, block, unblock user, current_role
Управление группами update, delete group_name
add_members, remove_members group_name, users — по порядку payload; у длинного списка только первые участники
Управление согласованием action_setting action_display_name, group_name
admins users — по порядку payload; у длинного списка только первые
settings action_names — названия действий по action_key, group_names — названия групп по uuid, users — администраторы кворума и участники групп из payload.base и payload.target; у длинного списка только первые
Добавление адреса в белый список нет whitelisted_wallet_name, currency_symbol, currency_descriptor, blockchain_name
Управление тегами update, delete tag
attach_detach vaults, tags
Управление политиками update policy_type_name
rollback policy_type_name, version_published_at

Остальные операции приходят без display: их payload читается как есть.

Настройки кворума

GET …/quorum отдаёт порог, правила всех действий, состав подтверждающих и подпись настроек:

{
  "admin_quorum_threshold": 2,
  "actions": [ { "action_key": "<action_key>", "…": "…" } ],
  "owner_approvers": ["5b2f…"],
  "admin_quorum_approvers": ["c71e…", "e04a…"],
  "admin_quorum_members": ["c71e…", "e04a…"],
  "signature": {
    "state": "QUORUM_SETTINGS_STATE_SIGNED",
    "version": 3,
    "snapshot_hash": "3712b95f…",
    "fingerprint": "3712 B95F …",
    "signed_at": "2026-10-20T09:12:00Z",
    "verified": true,
    "mismatch": "",
    "snapshot": { "admin_quorum_threshold": 2, "rules": [{ "…": "…" }], "groups": [{ "…": "…" }], "admins": ["…"] },
    "current": { "admin_quorum_threshold": 2, "rules": [{ "…": "…" }], "groups": [{ "…": "…" }], "admins": ["…"] }
  }
}
Поле Что содержит
approver_sets, reachable у правила кто подтверждал бы сейчас, без учёта того, над кем изменение, и набирает ли состав порог; есть и у выключенных правил
owner_approvers, admin_quorum_approvers кто прямо сейчас подтверждает как владелец и как администратор кворума, независимо от правил
admin_quorum_members все назначенные администраторы кворума, в том числе те, кто сейчас подтверждать не может
signature.state состояние настроек, см. Настройки под подписью владельца
signature.version, snapshot_hash, fingerprint, signed_at последняя подписанная версия; без неё — 0 и пустые строки; поля signed_at нет и тогда, когда версия не проходит проверку
signature.verified, mismatch true — расхождения нет, в том числе пока версий нет; false — настройки расходятся с подписанной версией, в mismatch — код расхождения для поддержки
signature.snapshot подписанная версия в форме settings; поля нет, если версии нет или она не проходит проверку
signature.current текущие настройки в форме settings, от них строится новая версия; поля нет при QUORUM_SETTINGS_STATE_DISABLED
active_member_uuids у группы в списке групп действующие участники группы; при QUORUM_SETTINGS_STATE_SIGNED из них подтверждают вошедшие в подписанную версию, см. approver_sets
quorum_protected у группы в списке групп и в её карточке группа выбрана в правиле, даже выключенном, см. «Кто подтверждает»

Состав ещё не сохранённого правила считается из этих пулов, участников группы и порога.

Новая версия настроек

PUT …/quorum/settings отправляет настройки целиком на подпись владельцу. Ответ — 403 QUORUM_APPROVAL_REQUIRED: версия вступит в силу, когда владелец подтвердит запрос.

PUT /api/v2/admin/tenants/{tenant_uuid}/quorum/settings
{
  "base_version": 3,
  "settings": {
    "admin_quorum_threshold": 2,
    "rules": [
      { "action_key": "<action_key>", "is_enabled": true, "mode": "QUORUM_APPROVAL_MODE_SPECIFIC_GROUP",
        "group_uuid": "33f1…", "group_threshold": 2, "owner_approval": true, "admins_can_cancel": false },
      { "action_key": "<action_key>", "is_enabled": false, "mode": "QUORUM_APPROVAL_MODE_OWNER_ONLY",
        "group_threshold": 1, "owner_approval": false, "admins_can_cancel": false }
    ],
    "groups": [ { "group_uuid": "33f1…", "members": ["5b2f…", "7d1e…", "9a4c…"] } ],
    "admins": ["c71e…", "e04a…"]
  }
}
{
  "error": "change requires quorum approval",
  "code": "QUORUM_APPROVAL_REQUIRED",
  "details": {
    "approval_request_uuid": "3f0c5c1e-…",
    "action": "<action_key>",
    "operation": "settings",
    "mode": "QUORUM_APPROVAL_MODE_OWNER_ONLY",
    "expires_at": "2026-10-23T10:00:00Z",
    "version": 4,
    "snapshot_hash": "5d41…",
    "fingerprint": "5D41 402A …"
  }
}
Поле Что содержит
base_version signature.version, от которой сделаны изменения; у первой версии — 0
settings.rules правило каждого действия из GET …/quorum/actions, по одному; у действия с fixed_mode — этот режим, owner_approval и admins_can_cancel — false; group_threshold — 1..1000
settings.groups ровно группы, выбранные в правилах, с полным текущим составом: из signature.current, а у группы, которую правила ещё не выбирали, — из всех страниц members её карточки
settings.admins администраторы кворума целиком
details.version, snapshot_hash, fingerprint номер новой версии, её хэш и отпечаток по расчёту платформы; сравните их со своими, а владельцу показывайте отпечаток, посчитанный у себя

В карточке запроса payload несёт version, base_version, base — версию, от которой сделаны изменения (у первой версии — прежние настройки или null), и target — новую версию; режим в них записан кодом канонической записи.

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

Ответ Когда
400 VALIDATION_ERROR settings не по описанию полей выше: admin_quorum_threshold вне 1..1000; правило не на каждое действие или повтор, лишняя группа или группа правила не в groups, больше 100 правил; повтор или нулевой uuid в admins и members; group_threshold без поля или 0; при QUORUM_SETTINGS_STATE_DISABLED
400 QUORUM_ACTION_UNKNOWN правило для действия, которого нет у рабочего пространства, или настройки кворума к рабочему пространству неприменимы
409 TENANT_INACTIVE рабочее пространство неактивно
403 QUORUM_CHANGE_REQUESTS_DISABLED версию отправил администратор после первой подписанной версии, а «Управление согласованием» выключено
409 QUORUM_SETTINGS_NOT_SIGNED версию отправил администратор до первой подписанной версии, при любом состоянии «Управления согласованием»
409 QUORUM_SETTINGS_VERSION_CONFLICT base_version не последняя подписанная версия (последняя — в details.version) или состав группы изменился после чтения: перечитайте настройки
409 QUORUM_NO_ELIGIBLE_APPROVERS включённое правило версии сейчас не набирает порог, details.action_keys — такие действия; без details.action_keys — версию сейчас некому подтвердить: владелец не вправе подтверждать
409 CHANGE_REQUEST_IN_PROGRESS другая версия уже ждёт подписи или применяется
409 QUORUM_SETTINGS_UNVERIFIED последняя подписанная версия или запись о ней не проходят проверку: новую версию от неё построить нельзя, обратитесь в поддержку

Настройки по одной

При QUORUM_SETTINGS_STATE_DISABLED настройки меняются по одной. Правило действия задаёт PUT …/quorum/actions/{action_key}; ответ — сохранённое правило с составом подтверждающих. group_threshold без поля — 1; admins_can_cancel без поля сохраняет прежнее значение.

PUT /api/v2/admin/tenants/{tenant_uuid}/quorum/actions/{action_key}
{
  "is_enabled": true,
  "mode": "QUORUM_APPROVAL_MODE_SPECIFIC_GROUP",
  "group_uuid": "33f1…",
  "group_threshold": 2,
  "owner_approval": false,
  "admins_can_cancel": false
}
{
  "setting": {
    "action_key": "<action_key>",
    "display_name": "Manage users",
    "is_enabled": true,
    "mode": "QUORUM_APPROVAL_MODE_SPECIFIC_GROUP",
    "group_uuid": "33f1…",
    "group_threshold": 2,
    "owner_approval": false,
    "admins_can_cancel": false,
    "approver_sets": [ { "external_id": "A", "threshold": 2, "user_uuids": [ "5b2f…", "7d1e…", "9a4c…" ] } ],
    "reachable": true
  }
}

Порог кворума администраторов задаёт PUT …/quorum/threshold с телом {"admin_quorum_threshold": 2} (1..1000); ответ — настройки целиком, как у GET …/quorum.

Администраторов кворума задаёт PUT …/quorum/admins: список целиком, порядок и повторы не важны; пустой список или тело без user_uuids снимает всех. Ответ — настройки целиком, как у GET …/quorum.

PUT /api/v2/admin/tenants/{tenant_uuid}/quorum/admins
{ "user_uuids": ["c71e…", "e04a…"] }
Запись по одной Ответ
PUT правила без mode, с group_uuid не в режиме «Группа» или без него в режиме «Группа», с group_threshold больше 1000 (без поля или 0 — порог 1) 400 VALIDATION_ERROR
PUT правила действия с fixed_mode («Управление согласованием») в другом режиме, с группой или с admins_can_cancel 400 VALIDATION_ERROR
PUT порога администраторов вне 1..1000 400 VALIDATION_ERROR
PUT администраторов кворума со списком больше 1000 разных пользователей, с нулевым или некорректным uuid 400 VALIDATION_ERROR
PUT администраторов кворума, добавляющий пользователя без роли администратора, API-пользователя или удалённого пользователя QUORUM_ADMIN_NOT_ELIGIBLE; в details.user_uuids — такие пользователи
группа из group_uuid не найдена GROUP_NOT_FOUND
группа из другого рабочего пространства QUORUM_GROUP_NOT_IN_TENANT
администратор, пока «Управление согласованием» выключено 403 QUORUM_CHANGE_REQUESTS_DISABLED
любая, если signature.state не QUORUM_SETTINGS_STATE_DISABLED 409 QUORUM_SETTINGS_SNAPSHOT_REQUIRED

Описание изменения

changes описывает изменение так, что его можно показать, не зная схемы payload действия: секции (например, правила политики) с полями «было» и «стало».

Действие changes
управление политиками (update, rollback), управление тегами (все операции), добавление адреса в белый список, one-time адреса есть; если описание не собралось — как у остальных действий
остальные действия поля changes нет, summary и changes_hash пусты; показывайте запрос по display

Пример — фрагмент карточки с описанием изменения правила политики: выросла сумма и изменился набор аппруверов A (остальные поля карточки, поля со значениями по умолчанию и часть шаблонов texts опущены):

{
  "request": {
    "request_uuid": "3f0c5c1e-…",
    "changes": {
      "schema_version": 1,
      "summary": { "code": "policy.summary.update.transfer", "args": { "rules": "1" } },
      "sections": [
        {
          "id": "5b0d2f1c-…", "kind": "policy.rule", "op": "CHANGE_VIEW_OP_MODIFIED",
          "title": { "code": "policy.rule.title", "args": { "name": "Large transfers" } },
          "position_before": 3, "position_after": 1,
          "fields": [
            { "id": "amount", "label": { "code": "policy.field.amount" }, "op": "CHANGE_VIEW_OP_MODIFIED",
              "before": { "money": { "amount": "1000", "currency": "USD" } },
              "after": { "money": { "amount": "5000", "currency": "USD" } } },
            { "id": "approval.sets.A.members", "op": "CHANGE_VIEW_OP_MODIFIED",
              "label": { "code": "policy.field.approval.set.members", "args": { "set": "A" } },
              "after": { "set": { "items": [
                { "op": "CHANGE_VIEW_OP_ADDED", "value": { "entity": { "kind": "user_group", "id": "33f1…" } } }
              ] } } },
            { "id": "approval.sets.A.threshold", "op": "CHANGE_VIEW_OP_MODIFIED", "important": true,
              "label": { "code": "policy.field.approval.set.threshold", "args": { "set": "A" } },
              "before": { "number": "2" }, "after": { "number": "1" } }
          ]
        }
      ],
      "notes": [],
      "texts": {
        "policy.summary.update.transfer": { "by_locale": { "en": "Transfers policy: {rules} rule(s) affected", "ru": "Политика переводов: затронуто правил — {rules}" } },
        "policy.field.amount": { "by_locale": { "en": "Amount from", "ru": "Сумма от" } }
      }
    },
    "summary": { "en": "Transfers policy: 1 rule(s) affected", "ru": "Политика переводов: затронуто правил — 1" },
    "changes_hash": "9f2c…",
    "entities": { "user_group:33f1…": { "name": "Finance" } }
  }
}
Поле changes Что содержит
summary однострочная сводка — текст
fields поля верхнего уровня — у простых изменений (порог 2 → 3)
sections секции — у составных изменений, в порядке показа; у секции id, kind (подсказка для особого показа, например policy.rule), title, op, позиции, fields, вложенные sections, notes и hidden_unchanged — сколько неизменённых полей и секций не перечислено
notes пояснения и предупреждения: severity — CHANGE_VIEW_NOTE_SEVERITY_INFO или CHANGE_VIEW_NOTE_SEVERITY_WARNING; пустое значение и CHANGE_VIEW_NOTE_SEVERITY_UNSPECIFIED показываются как CHANGE_VIEW_NOTE_SEVERITY_INFO, незнакомое — как CHANGE_VIEW_NOTE_SEVERITY_WARNING; text
truncated описание урезано по размеру и показывает не всё
texts шаблоны текстов: код → by_locale → шаблон
schema_version сейчас 1; у описания старшей версии показывается сводка, а само изменение — по display, как у запроса без описания

Текст приходит кодом и аргументами (code, args). Шаблон кода берётся из словаря клиента, иначе из texts на локали клиента, иначе на en, иначе показывается сам код.

Подстановка — имя аргумента в фигурных скобках: строчные латинские буквы, цифры и _. Она делается за один проход: {set} заменяется на args.set, {…} внутри значения аргумента не раскрывается, подстановка без аргумента и прочие скобки остаются как есть.

Значение аргумента — готовая строка, часто текст пользователя, например название правила. Показывайте каждое значение изолированно от соседнего текста, как элемент bdi в HTML: символы направления текста в нём не должны переставлять остальную строку.

op Секция Поле
CHANGE_VIEW_OP_ADDED добавлена; position_before — 0 значение в after
CHANGE_VIEW_OP_REMOVED удалена; position_after — 0 значение в before
CHANGE_VIEW_OP_MODIFIED изменена; позиции могут различаться before и after; у множества — after с элементами, отмеченными CHANGE_VIEW_OP_ADDED и CHANGE_VIEW_OP_REMOVED
CHANGE_VIEW_OP_MOVED изменилась только позиция —
CHANGE_VIEW_OP_UNCHANGED без изменений, показана для контекста значение в after

important у поля — изменение ослабляет контроль: снятие запрета, снижение порога.

Вид значения Что содержит
text текст кодом и аргументами
literal строка как есть: название, адрес
flag, number да или нет; десятичное число
money amount в валюте currency (USD) или, без currency, в единицах актива asset; при minor_units — в минимальных единицах актива
entity сущность kind и id: имя — из entities карточки, если ключ там есть и не missing, иначе name снимка, а без него — id; subtitle — уточнение; missing — сущности нет; виды — в таблице ниже
enum_value label для показа, code — значение
set элементы items с value и op: в изменённом множестве — CHANGE_VIEW_OP_ADDED или CHANGE_VIEW_OP_REMOVED, элемент как есть — CHANGE_VIEW_OP_UNSPECIFIED или CHANGE_VIEW_OP_UNCHANGED; omitted — сколько элементов не перечислено
list упорядоченный список items; omitted
time, unset время; значение не задано
незнакомый вид показывается строка fallback
kind сущности Что это Имя
user, service_account, user_group пользователь, сервисный аккаунт, группа свежее, в entities карточки
vault аккаунт снимок в name на момент создания запроса
tag тег снимок в name
whitelisted_wallet внешний (whitelisted) кошелёк снимок в name; subtitle — тип: internal, external, contract
asset актив снимок: name — символ, subtitle — сеть