Updated comments and docs

app/controllers/api/users.php

@@ -1233,7 +1233,7 @@ Http::patch('/v1/users/:userId/impersonator')
         ]
     ))
     ->param('userId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'User ID.', false, ['dbForProject'])
-    ->param('impersonator', false, new Boolean(true), 'Whether the user can impersonate other users. When true, the user can pass impersonation headers to act as another user.')
+    ->param('impersonator', false, new Boolean(true), 'Whether the user can impersonate other users. When true, the user can browse project users to choose a target and can pass impersonation headers to act as that user.')
     ->inject('response')
     ->inject('dbForProject')
     ->inject('queueForEvents')

app/controllers/shared/api.php

@@ -338,7 +338,8 @@ Http::init()
 
         $scopes = \array_unique($scopes);
 
-        // Impersonators can browse users before and during impersonation.
+        // Intentional: impersonators get users.read so they can discover a target user
+        // before impersonation starts, and keep that access while impersonating.
         if (
             !$user->isEmpty()
             && (

src/Appwrite/Platform/Tasks/Specs.php

@@ -163,19 +163,19 @@ class Specs extends Action
                 'ImpersonateUserId' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Id',
-                    'description' => 'Impersonate a user by ID. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by ID on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
                 'ImpersonateUserEmail' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Email',
-                    'description' => 'Impersonate a user by email. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by email on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
                 'ImpersonateUserPhone' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Phone',
-                    'description' => 'Impersonate a user by phone. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by phone on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
             ],
@@ -219,19 +219,19 @@ class Specs extends Action
                 'ImpersonateUserId' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Id',
-                    'description' => 'Impersonate a user by ID. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by ID on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
                 'ImpersonateUserEmail' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Email',
-                    'description' => 'Impersonate a user by email. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by email on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
                 'ImpersonateUserPhone' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Phone',
-                    'description' => 'Impersonate a user by phone. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by phone on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
             ],
@@ -275,19 +275,19 @@ class Specs extends Action
                 'ImpersonateUserId' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Id',
-                    'description' => 'Impersonate a user by ID. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by ID on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
                 'ImpersonateUserEmail' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Email',
-                    'description' => 'Impersonate a user by email. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by email on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
                 'ImpersonateUserPhone' => [
                     'type' => 'apiKey',
                     'name' => 'X-Appwrite-Impersonate-User-Phone',
-                    'description' => 'Impersonate a user by phone. Requires the current user to have impersonator capability.',
+                    'description' => 'Impersonate a user by phone on an already user-authenticated request. Requires the current request to be authenticated as a user with impersonator capability; X-Appwrite-Key alone is not sufficient. Impersonator users are intentionally granted users.read so they can discover a target before impersonation begins.',
                     'in' => 'header',
                 ],
             ],

src/Appwrite/Utopia/Response/Model/Account.php

@@ -118,7 +118,7 @@ class Account extends Model
             ])
             ->addRule('impersonatorUserId', [
                 'type' => self::TYPE_STRING,
-                'description' => 'When present, the current session is impersonating this user ID. Only set when the request used impersonation headers.',
+                'description' => 'ID of the user performing the impersonation. Present only when the current request is impersonating another user.',
                 'required' => false,
                 'default' => '',
                 'example' => '5e5ea5c16897e',

src/Appwrite/Utopia/Response/Model/User.php

@@ -148,7 +148,7 @@ class User extends Model
             ])
             ->addRule('impersonatorUserId', [
                 'type' => self::TYPE_STRING,
-                'description' => 'When present, the current session is impersonating this user ID. Only set when the request used impersonation headers.',
+                'description' => 'ID of the user performing the impersonation. Present only when the current request is impersonating another user.',
                 'required' => false,
                 'default' => '',
                 'example' => '5e5ea5c16897e',