From 1fac6b3c2fa0d7bd6c6d0f179a1ad8c6dde9b23a Mon Sep 17 00:00:00 2001
From: Lars Erik Wik <lars.erik.wik@northern.tech>
Date: Tue, 27 Oct 2026 17:28:22 +0100
Subject: [PATCH] Documented the user_added and user_removed event types

Ticket: ENT-14765
Signed-off-by: Lars Erik Wik <lars.erik.wik@northern.tech>
---
 .../reference/promise-types/events.markdown   | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/content/reference/promise-types/events.markdown b/content/reference/promise-types/events.markdown
index 229a68a0b..bd79e0e61 100644
--- a/content/reference/promise-types/events.markdown
+++ b/content/reference/promise-types/events.markdown
@@ -274,3 +274,52 @@ Required with `file_size_exceeds`, and can't be used with other event types.
 **Type:** `int`
 
 **Allowed input range:** `0,99999999999`
+
+#### User event type
+
+##### User added
+
+**Description:** Creates an event when the user with the given name is added.
+
+The event fires when the user was missing at one check and exists at the next one.
+It fires once per addition: the user has to be removed again before another addition is detected.
+On Windows, only user accounts count, not groups or built-in accounts such as `SYSTEM`.
+
+```cf3
+body when added(user)
+{
+  user_added => "$(user)";
+}
+```
+
+**Type:** `string`
+
+**Allowed input range:** (arbitrary string)
+
+**Notes:**
+
+- On Unix, users from network sources such as LDAP or sssd are not detected.
+
+##### User removed
+
+**Description:** Creates an event when the user with the given name is removed.
+
+The event fires when the user existed at one check and is missing at the next one.
+It fires once per removal: the user has to be added again before another removal is detected.
+A failing lookup of the user is logged as an error, and is not taken as a removal.
+On Windows, only user accounts count (`SidTypeUser`), not groups or built-in accounts such as `SYSTEM`.
+
+```cf3
+body when removed(user)
+{
+  user_removed => "$(user)";
+}
+```
+
+**Type:** `string`
+
+**Allowed input range:** (arbitrary string)
+
+**Notes:**
+
+- On Unix, users from network sources such as LDAP or sssd may not be detected.