Журнал аудита событий
audit_events:read, который доступен только владельцу пространства.Журнал аудита отдаёт командам безопасности лог действий в пространстве: кто, что и когда сделал, с какого адреса и с какого клиента. По нему расследуют инциденты, отслеживают изменения прав и собирают отчётность для регуляторов.
Записи возвращает метод GETЖурнал аудита событий. Журнал доступен только на чтение, изменить или удалить запись нельзя.
Что попадает в журнал
- События записываются только для пространств на тарифе Корпорация. Пока тариф не подключён, журнал не наполняется, и после подключения прошлые действия в нём не появятся.
- У каждого события есть актор — сотрудник или бот, выполнивший действие. Действия без актора в журнал не попадают. Исключение — событие
oauth_token_revoked: его актор — приложение, которое отозвало свой токен. - Данные собираются с 12 мая 2025 года.
- Чтение самого журнала тоже событие: каждый запрос к методу пишет
audit_events_accessed. - Так же логируется инвентаризация пространства: GETСписок чатов пространства пишет
company_chats_accessed, GETСписок ботов пространства —company_bots_accessed. В обоих случаях актором и объектом события выступает владелец токена.
Структура записи
| Поле | Тип | Что внутри |
|---|---|---|
id | string | Идентификатор записи (UUID) |
created_at | string | Дата и время события (ISO-8601, UTC+0) |
event_key | string | Тип события. Полный список — ниже |
actor_id | string | Идентификатор сотрудника или бота, выполнившего действие |
actor_type | string | Тип актора: User, а у события oauth_token_revoked — Doorkeeper::Application |
entity_id | string | Идентификатор объекта, которого касается событие |
entity_type | string | Тип этого объекта, например User, Chat, Message, Reaction, GroupTag, TopicThread, VideoRoom или AccessToken |
details | object | Подробности события, состав зависит от event_key. Для событий без подробностей — пустой объект |
ip_address | string, null | IP-адрес запроса, в котором произошло действие |
user_agent | string, null | User agent клиента, обрезается до 255 символов |
actor_id, entity_id) приходят строками, а внутри details — числами. Это разные представления одного и того же идентификатора, приводите их к одному типу перед сравнением.Поля ip_address и user_agent заполняются из HTTP-запроса, в котором произошло действие. У событий, которые пишет сервер сам, без запроса пользователя — например, завершение видеозвонка по таймауту — оба поля приходят как null.
Типы событий
Токены и авторизации в журнале
Журнал записывает выдачу и отзыв каждого доступа к API. Вид доступа приходит в деталях в поле token_kind, а его владелец — в resource_owner_id.
| Что произошло | Событие |
|---|---|
| Создан, изменён или удалён персональный токен | access_token_created, access_token_updated, access_token_destroy |
| Сотрудник подтвердил или отклонил вход в CLI | oauth_device_authorization_approved, oauth_device_authorization_denied |
| Вход в CLI завершён в интерфейсе | access_token_destroy |
Вход в CLI завершён командой pachca auth logout | oauth_token_revoked |
| Боту выпущен токен, в том числе первый при создании бота | bot_token_created |
| У токена бота изменены название или права | bot_token_updated |
| Токен бота перевыпущен | bot_token_reissued, bot_token_recreated |
| Токен бота удалён | bot_token_deleted |
| Сотрудник разрешил боту действовать от своего имени | oauth_authorization_granted |
| Доступ бота отозван в интерфейсе | oauth_authorization_revoked |
| Бот сам отозвал выданный ему токен | oauth_token_revoked |
| Боту выпущен или обновлён секрет клиента | bot_oauth_client_secret_issued, bot_oauth_client_secret_rotated |
Отзыв в интерфейсе записывается от имени того, кто его выполнил. Когда чужой доступ закрывает администратор на вкладке Все токены, в actor_id приходит он, а владелец доступа остаётся в деталях: в resource_owner_id у токена и в user_id у авторизации бота.
У события oauth_token_revoked актор — приложение, поэтому в actor_id приходит не идентификатор сотрудника. Сотрудник, чей токен отозван, указан в resource_owner_id.
Обмен кода на токен и обновление токена отдельных записей не оставляют: выдачу фиксирует согласие сотрудника.
Вход по QR-коду в журнале
Сотрудник, который уже вошёл в Пачку на компьютере, может войти в мобильное приложение по QR-коду: приложение сканирует код с экрана компьютера, а сотрудник подтверждает вход, введя на компьютере две цифры с экрана телефона.
| Что произошло | Событие |
|---|---|
| Сотрудник открыл на компьютере QR-код для входа | login_grant_created |
| Сотрудник ввёл цифры с экрана телефона и подтвердил вход | login_grant_approved |
| Сотрудник отклонил вход или ввёл не те цифры | login_grant_denied |
| Приложение вошло в аккаунт | user_login |
Все записи одного входа связывает login_grant_id в деталях. События login_grant_created, login_grant_approved и login_grant_denied приходят с IP-адресом и user agent клиента на компьютере, а user_login — телефона. Если код не подтвердили вовремя, отдельной записи нет.
Если приложение не завершило вход, например не успело вовремя после подтверждения (на это есть не больше минуты) или подтвердившую сессию на компьютере завершили, за login_grant_approved не следует user_login. Записи user_login нет и тогда, когда приложение уже вошло в этот аккаунт раньше.
Название, платформу и версии устройства в device присылает само приложение, сервер сверяет только их формат. Подмену устройства отсекает проверка цифр: при несовпадении вход сразу отклоняется с reason: verification_failed, второй попытки нет.
Вход по QR-коду не запрашивает двухфакторную аутентификацию: личность уже подтверждена сессией на компьютере. Событий user_2fa_success и user_2fa_fail у такого входа нет.
Что приходит в деталях
Состав details зависит от типа события. События, которых нет в таблице, приходят с пустым объектом: вся информация о них уже есть в actor_id и entity_id.
| Тип события | Поля details |
|---|---|
user_login | method со значением qr и login_grant_id — при входе по QR-коду. При остальных способах входа — пустой объект |
login_grant_created | login_grant_id |
login_grant_approved | login_grant_id, device — объект с полями name, platform, os_version и app_version |
login_grant_denied | login_grant_id, device, reason — denied, если сотрудник отклонил вход, или verification_failed, если он ввёл не те цифры |
user_updated | changed_attrs — список изменённых полей. context — присутствует со значением sso_login, если профиль обновился автоматически при входе через SSO |
user_role_changed | new_company_role, previous_company_role, initiator_id |
user_chat_join | inviter_id |
user_chat_leave, user_added_to_tag, user_removed_from_tag | initiator_id |
chat_renamed | old_name, new_name |
chat_permission_changed | public_access |
tag_created, tag_deleted | name |
tag_added_to_chat | chat_id, tag_name |
tag_removed_from_chat | chat_id |
access_token_created, access_token_updated, access_token_destroy, bot_token_created, bot_token_reissued, bot_token_recreated, bot_token_deleted, oauth_token_revoked | token_kind, token_name, resource_owner_id, scopes. bot_id — у токенов бота и токенов, которые сотрудник выдал боту |
bot_token_updated | token_kind, token_name, resource_owner_id, current_scopes, bot_id, actor_id |
bot_deleted | bot_id, actor_id |
bot_scopes_updated | added_scopes, removed_scopes |
bot_webhook_settings_updated | changes — объект, где ключ это имя настройки, а значение содержит previous и new |
bot_oauth_client_updated | client_id, changes — объект, где ключ это имя параметра клиента, а значение содержит previous и new |
oauth_authorization_granted | client_id, scopes |
bot_oauth_client_secret_issued, bot_oauth_client_secret_rotated | bot_id, actor_id, client_id |
bot_oauth_client_disabled | bot_id, actor_id, client_id, deleted_access_tokens_count, deleted_access_grants_count |
oauth_authorization_revoked | client_id, revoked_tokens_count. user_id — когда доступ сотрудника отозвал администратор |
oauth_device_authorization_approved, oauth_device_authorization_denied | client_id, scopes, device_name |
kms_encrypt, kms_decrypt | chat_id, message_id, reason |
dlp_violation_detected | dlp_rule_id, dlp_rule_name, message_id, chat_id, user_id, action_message, conditions_matched |
search_users_api, search_chats_api, search_messages_api | search_type, query_present, cursor_present, limit, filters |
video_call_started | chat_id, started_message_id |
video_call_finished | chat_id, started_message_id, duration, max_members_count |
video_call_recording_ready | chat_id, started_message_id, recording_id, file_id, duration, size |
В записях до 7 октября 2026 года у событий токенов деталей меньше: у персональных токенов только scopes, у токенов бота — bot_id и actor_id.
Полные схемы с типами и описанием каждого поля — в разделе «Ответ» на странице метода GETЖурнал аудита событий, в поле details.
Фильтры
Все параметры фильтрации необязательны и комбинируются между собой.
| Параметр | Что отбирает |
|---|---|
start_time, end_time | Период по времени события, границы включительно |
event_key | Один тип события за запрос. Чтобы собрать несколько типов, сделайте несколько запросов |
actor_id, actor_type | Кто выполнил действие |
entity_id, entity_type | Над каким объектом |
Пагинация и слежение за новыми событиями
Метод отдаёт записи от новых к старым и использует курсорную пагинацию: limit до 50 записей за запрос, cursor из meta.paginate.next_page для следующей страницы.
Для регулярной выгрузки в SIEM удобнее курсор meta.paginate.prev_page: он указывает на начало списка, и запрос с ним возвращает только те события, которые появились после предыдущей выгрузки. Сохраняйте prev_page между запусками, вместо того чтобы каждый раз перебирать журнал с начала.
Примеры использования
Хранение данных
Журналы аудита хранятся в течение 90 дней для баланса между требованиями соответствия и эффективностью хранения. Все журналы неизменяемы и хранятся в системе только для чтения, чтобы обеспечить целостность данных.
Типичные сценарии использования
- Расследовать подозрительные попытки входа в систему
- Отслеживать изменения прав доступа
- Проверять, кто и когда выдавал и отзывал токены и доступы ботов
- Отслеживать действия по удалению сообщений
- Расследовать изменения ролей пользователей
- Отслеживать изменения в составе участников чатов
- Отслеживать срабатывания правил DLP-системы (
event_key: "dlp_violation_detected") - Составлять отчеты о соответствии требованиям и во время аудита