diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 2281385830..d526072d2f 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -19,20 +19,6 @@ It returns a JSON body like the following:
{
"name": "@user:example.com",
"displayname": "User", // can be null if not set
- "threepids": [
- {
- "medium": "email",
- "address": "<user_mail_1>",
- "added_at": 1586458409743,
- "validated_at": 1586458409743
- },
- {
- "medium": "email",
- "address": "<user_mail_2>",
- "added_at": 1586458409743,
- "validated_at": 1586458409743
- }
- ],
"avatar_url": "<avatar_url>", // can be null if not set
"is_guest": 0,
"admin": 0,
@@ -40,6 +26,7 @@ It returns a JSON body like the following:
"erased": false,
"shadow_banned": 0,
"creation_ts": 1560432506,
+ "last_seen_ts": 1732919539393,
"appservice_id": null,
"consent_server_notice_sent": null,
"consent_version": null,
@@ -55,7 +42,8 @@ It returns a JSON body like the following:
}
],
"user_type": null,
- "locked": false
+ "locked": false,
+ "suspended": false
}
```
@@ -82,16 +70,6 @@ with a body of:
"logout_devices": false,
"displayname": "Alice Marigold",
"avatar_url": "mxc://example.com/abcde12345",
- "threepids": [
- {
- "medium": "email",
- "address": "alice@example.com"
- },
- {
- "medium": "email",
- "address": "alice@domain.org"
- }
- ],
"external_ids": [
{
"auth_provider": "example",
@@ -128,15 +106,6 @@ Body parameters:
- `avatar_url` - **string**, optional. Must be a
[MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris).
If set to an empty string (`""`), the user's avatar is removed.
-- `threepids` - **array**, optional. If provided, the user's third-party IDs (email, msisdn) are
- entirely replaced with the given list. Each item in the array is an object with the following
- fields:
- - `medium` - **string**, required. The type of third-party ID, either `email` or `msisdn` (phone number).
- - `address` - **string**, required. The third-party ID itself, e.g. `alice@example.com` for `email` or
- `447470274584` (for a phone number with country code "44") and `19254857364` (for a phone number
- with country code "1") for `msisdn`.
- Note: If a threepid is removed from a user via this option, Synapse will also attempt to remove
- that threepid from any identity servers it is aware has a binding for it.
- `external_ids` - **array**, optional. Allow setting the identifier of the external identity
provider for SSO (Single sign-on). More details are in the configuration manual under the
sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
@@ -161,7 +130,8 @@ Body parameters:
- `locked` - **bool**, optional. If unspecified, locked state will be left unchanged.
- `user_type` - **string** or null, optional. If not provided, the user type will be
not be changed. If `null` is given, the user type will be cleared.
- Other allowed options are: `bot` and `support`.
+ Other allowed options are: `bot` and `support` and any extra values defined in the homserver
+ [configuration](../usage/configuration/config_documentation.md#user_types).
## List Accounts
### List Accounts (V2)
@@ -412,6 +382,32 @@ The following actions are **NOT** performed. The list may be incomplete.
- Remove from monthly active users
- Remove user's consent information (consent version and timestamp)
+## Suspend/Unsuspend Account
+
+This API allows an admin to suspend/unsuspend an account. While an account is suspended, the user is
+prohibited from sending invites, joining or knocking on rooms, sending messages, changing profile data, and redacting messages other than their own.
+
+The api is:
+
+```
+PUT /_synapse/admin/v1/suspend/<user_id>
+```
+
+with a body of:
+
+```json
+{
+ "suspend": true
+}
+```
+
+To unsuspend a user, use the same endpoint with a body of:
+```json
+{
+ "suspend": false
+}
+```
+
## Reset password
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
@@ -476,9 +472,9 @@ with a body of:
}
```
-## List room memberships of a user
+## List joined rooms of a user
-Gets a list of all `room_id` that a specific `user_id` is member.
+Gets a list of all `room_id` that a specific `user_id` is joined to and is a member of (participating in).
The API is:
@@ -515,6 +511,73 @@ The following fields are returned in the JSON response body:
- `joined_rooms` - An array of `room_id`.
- `total` - Number of rooms.
+## Get the number of invites sent by the user
+
+Fetches the number of invites sent by the provided user ID across all rooms
+after the given timestamp.
+
+```
+GET /_synapse/admin/v1/users/$user_id/sent_invite_count
+```
+
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `user_id`: fully qualified: for example, `@user:server.com`
+
+The following should be set as query parameters in the URL:
+
+* `from_ts`: int, required. A timestamp in ms from the unix epoch. Only
+ invites sent at or after the provided timestamp will be returned.
+ This works by comparing the provided timestamp to the `received_ts`
+ column in the `events` table.
+ Note: https://currentmillis.com/ is a useful tool for converting dates
+ into timestamps and vice versa.
+
+A response body like the following is returned:
+
+```json
+{
+ "invite_count": 30
+}
+```
+
+_Added in Synapse 1.122.0_
+
+## Get the cumulative number of rooms a user has joined after a given timestamp
+
+Fetches the number of rooms that the user joined after the given timestamp, even
+if they have subsequently left/been banned from those rooms.
+
+```
+GET /_synapse/admin/v1/users/$<user_id/cumulative_joined_room_count
+```
+
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `user_id`: fully qualified: for example, `@user:server.com`
+
+The following should be set as query parameters in the URL:
+
+* `from_ts`: int, required. A timestamp in ms from the unix epoch. Only
+ invites sent at or after the provided timestamp will be returned.
+ This works by comparing the provided timestamp to the `received_ts`
+ column in the `events` table.
+ Note: https://currentmillis.com/ is a useful tool for converting dates
+ into timestamps and vice versa.
+
+A response body like the following is returned:
+
+```json
+{
+ "cumulative_joined_room_count": 30
+}
+```
+_Added in Synapse 1.122.0_
+
## Account Data
Gets information about account data for a specific `user_id`.
@@ -859,7 +922,8 @@ A response body like the following is returned:
"last_seen_ip": "1.2.3.4",
"last_seen_user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0",
"last_seen_ts": 1474491775024,
- "user_id": "<user_id>"
+ "user_id": "<user_id>",
+ "dehydrated": false
},
{
"device_id": "AUIECTSRND",
@@ -867,7 +931,8 @@ A response body like the following is returned:
"last_seen_ip": "1.2.3.5",
"last_seen_user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0",
"last_seen_ts": 1474491775025,
- "user_id": "<user_id>"
+ "user_id": "<user_id>",
+ "dehydrated": false
}
],
"total": 2
@@ -897,6 +962,7 @@ The following fields are returned in the JSON response body:
- `last_seen_ts` - The timestamp (in milliseconds since the unix epoch) when this
devices was last seen. (May be a few minutes out of date, for efficiency reasons).
- `user_id` - Owner of device.
+ - `dehydrated` - Whether the device is a dehydrated device.
- `total` - Total number of user's devices.
@@ -1306,7 +1372,7 @@ When a user matched the given ID for the given provider, an HTTP code `200` with
The following parameters should be set in the URL:
- `provider` - The ID of the authentication provider, as advertised by the [`GET /_matrix/client/v3/login`](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3login) API in the `m.login.sso` authentication method.
-- `external_id` - The user ID from the authentication provider. Usually corresponds to the `sub` claim for OIDC providers, or to the `uid` attestation for SAML2 providers.
+- `external_id` - The user ID from the authentication provider. Usually corresponds to the `sub` claim for OIDC providers.
The `external_id` may have characters that are not URL-safe (typically `/`, `:` or `@`), so it is advised to URL-encode those parameters.
@@ -1324,19 +1390,28 @@ Returns a `404` HTTP status code if no user was found, with a response body like
_Added in Synapse 1.68.0._
-## Find a user based on their Third Party ID (ThreePID or 3PID)
+## Redact all the events of a user
-The API is:
+This endpoint allows an admin to redact the events of a given user. There are no restrictions on redactions for a
+local user. By default, we puppet the user who sent the message to redact it themselves. Redactions for non-local users are issued using the admin user, and will fail in rooms where the admin user is not admin/does not have the specified power level to issue redactions.
+The API is
```
-GET /_synapse/admin/v1/threepid/$medium/users/$address
+POST /_synapse/admin/v1/user/$user_id/redact
+
+{
+ "rooms": ["!roomid1", "!roomid2"]
+}
```
+If an empty list is provided as the key for `rooms`, all events in all the rooms the user is member of will be redacted,
+otherwise all the events in the rooms provided in the request will be redacted.
-When a user matched the given address for the given medium, an HTTP code `200` with a response body like the following is returned:
+The API starts redaction process running, and returns immediately with a JSON body with
+a redact id which can be used to query the status of the redaction process:
```json
{
- "user_id": "@hello:example.org"
+ "redact_id": "<opaque id>"
}
```
@@ -1344,20 +1419,57 @@ When a user matched the given address for the given medium, an HTTP code `200` w
The following parameters should be set in the URL:
-- `medium` - Kind of third-party ID, either `email` or `msisdn`.
-- `address` - Value of the third-party ID.
+- `user_id` - The fully qualified MXID of the user: for example, `@user:server.com`.
-The `address` may have characters that are not URL-safe, so it is advised to URL-encode those parameters.
+The following JSON body parameter must be provided:
-**Errors**
+- `rooms` - A list of rooms to redact the user's events in. If an empty list is provided all events in all rooms
+ the user is a member of will be redacted
-Returns a `404` HTTP status code if no user was found, with a response body like this:
+The following JSON body parameters are optional:
-```json
+- `reason` - Reason the redaction is being requested, ie "spam", "abuse", etc. This will be included in each redaction event, and be visible to users.
+- `limit` - a limit on the number of the user's events to search for ones that can be redacted (events are redacted newest to oldest) in each room, defaults to 1000 if not provided
+
+_Added in Synapse 1.116.0._
+
+
+## Check the status of a redaction process
+
+It is possible to query the status of the background task for redacting a user's events.
+The status can be queried up to 24 hours after completion of the task,
+or until Synapse is restarted (whichever happens first).
+
+The API is:
+
+```
+GET /_synapse/admin/v1/user/redact_status/$redact_id
+```
+
+A response body like the following is returned:
+
+```
{
- "errcode":"M_NOT_FOUND",
- "error":"User not found"
+ "status": "active",
+ "failed_redactions": [],
}
```
-_Added in Synapse 1.72.0._
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `redact_id` - string - The ID for this redaction process, provided when the redaction was requested.
+
+
+**Response**
+
+The following fields are returned in the JSON response body:
+
+- `status` - string - one of scheduled/active/completed/failed, indicating the status of the redaction job
+- `failed_redactions` - dictionary - the keys of the dict are event ids the process was unable to redact, if any, and the values are
+ the corresponding error that caused the redaction to fail
+
+_Added in Synapse 1.116.0._
+
+
|
