User Commands#
synadm user#
List, add, modify, deactivate/erase users, reset passwords.
synadm user [OPTIONS] COMMAND [ARGS]...
3pid#
Find a user based on their Third Party ID.
Finds a user based on their Third Party ID (3PID) where medium is the kind of Third Party ID that is used such as ‘email’ or ‘msidn’.
synadm user 3pid [OPTIONS] ADDRESS
Options
- -m, --medium <medium>#
Required Medium specifies what kind of Third Party ID is used such as ‘email’ or ‘msidn’
- Default:
email
Arguments
- ADDRESS#
Required argument
auth-provider#
Find a user based on their ID in auth-provider.
Finds a user based on their external user ID in a particular auth provider where provider is the auth provider ID as advertised in supported authenticated methods in m.login.sso api response such as ‘oidc’ or ‘google’ or ‘github’.
synadm user auth-provider [OPTIONS] EXTERNAL_USER_ID
Options
- -p, --provider <provider>#
Required Provider ID as advertised in supported authenticated methods in m.login.sso api response such as ‘oidc’ or ‘google’ or ‘github’
Arguments
- EXTERNAL_USER_ID#
Required argument
deactivate#
Deactivate or gdpr-erase a user. Provide matrix user ID (@user:server) as argument. It removes active access tokens, resets the password, and deletes third-party IDs (to prevent the user requesting a password reset).
synadm user deactivate [OPTIONS] USER_ID
Options
- -e, --gdpr-erase#
Marks the user as GDPR-erased. This means messages sent by the user will still be visible by anyone that was in the room when these messages were sent, but hidden from users joining the room afterwards.
- Default:
False
Arguments
- USER_ID#
Required argument
deactivate-regex#
Deactivate or GDPR-erase accounts based on regex.
Does everything normal deactivation does, just for multiple users matching the given regex.
The regex argument takes a string and uses Python’s re.match (matches regex starting from first character). A regex is expected to match a full Matrix ID, or partially at least from the first character.
–dry-run can be used to see which accounts will be deactivated. This can be useful for reviewing the accounts that will be deactivated.
Additionally, the –batch argument (given before the subcommands) will not prompt for if you want to deactivate a user (very useful for many users).
synadm user deactivate-regex [OPTIONS] REGEX
Options
- -e, --gdpr-erase#
Marks the users as GDPR-erased. This means messages sent by the users will still be visible by anyone that was in the room when these messages were sent, but hidden from other users joining the room afterwards.
- Default:
False
- -n, --dry-run#
Do everything except deactivating users.
- -p, --batch-size, --paginate <batch_size>#
How many users should be requested from the API one at a time. This option has no effect on how many users will be deactivated.
Increasing this is not necessary in most cases but useful if you have a lot of accounts on your homeserver.
- Default:
500
Arguments
- REGEX#
Required argument
details#
View details of a user account.
synadm user details [OPTIONS] USER_ID
Arguments
- USER_ID#
Required argument
list#
List users, search for users.
synadm user list [OPTIONS]
Options
- -f, --from <from_>#
Offset user listing by given number. This option is also used for pagination.
- Default:
0
- -l, --limit <limit>#
Limit user listing to given number
- Default:
100
- -g, --guests, -G, --no-guests#
Show guest users.
- -d, --deactivated#
Also show deactivated/erased users
- Default:
False
- -a, --admins, -A, --non-admins#
Whether to filter for admins, or non-admins. If not specified, no admin filter is applied.
- -n, --name <name>#
Search users by name - filters to only return users with user ID localparts or displaynames that contain this value (localpart is the left part before the colon of the matrix ID (@user:server)
- -i, --user-id <user_id>#
Search users by ID - filters to only return users with Matrix IDs (@user:server) that contain this value
login#
Get an access token for a given user.
Useful for when admins wish to do actions on behalf of a user.
If no –expire* option is given, a default token expiry time of exactly 1 day (24h) is used. If it’s desired that the token never expires, use –expire-never
This API does not generate a new device for the user, and so will not appear in their /devices list, and in general the target user should not be able to tell they have been logged in as.
To expire the token before the expiry date/time is reached, call the standard /logout API with the token. Note: The token will expire if the admin user calls /logout/all from any of their devices, but the token will not expire if the target user does the same.
synadm user login [OPTIONS] USER_ID
Options
- -d, --expire-days <expire_days>#
Expire token after this number of days.
- --expire <expire>#
Expire token after this point in time. Eg. ‘2021-01-01’, see above for available date/time formats.
- --expire-ts <expire_ts>#
Expire token after this point in time giving a unix timestamp in ms.
- --expire-never#
Never expire token.
- Default:
False
Arguments
- USER_ID#
Required argument
media#
List all local media uploaded by a user.
Provide matrix user ID (@user:server) as argument.
Gets a list of all local media that a specific user_id has created. By default, the response is ordered by descending creation date and ascending media ID. The newest media is on top. You can change the order with options –order-by and –reverse.
Caution. The database only has indexes on the columns media_id, user_id and created_ts. This means that if a different sort order is used (upload_name, last_access_ts, media_length, media_type, quarantined_by or safe_from_quarantine), this can cause a large load on the database, especially for large environments
synadm user media [OPTIONS] USER_ID
Options
- -f, --from <from_>#
Offset media listing by given number. This option is also used for pagination.
- Default:
0
- -l, --limit <limit>#
Limit media listing to given number
- Default:
100
- -s, --sort <sort>#
The method by which to sort the returned list of media. If the ordered field has duplicates, the second order is always by ascending media_id, which guarantees a stable ordering.
- Options:
media_id | upload_name | created_ts | last_access_ts | media_length | media_type | quarantined_by | safe_from_quarantine
- -r, --reverse#
Direction of media order. If set it will reverse the sort order of –order-by method.
- --datetime, --dt, --timestamp, --ts#
Display created and last accessed timestamps in a human readable format, or as a unix timestamp in milliseconds. [default: datetime].
Arguments
- USER_ID#
Required argument
membership#
List all rooms a user is member of.
Provide matrix user ID (@user:server) as argument.
synadm user membership [OPTIONS] USER_ID
Options
- --aliases, --ids#
Display rooms as canonical aliases or room ID’s. [default: aliases]
Arguments
- USER_ID#
Required argument
modify#
Create or modify a local user. Provide matrix user ID (@user:server) as argument.
synadm user modify [OPTIONS] USER_ID
Options
- -p, --password-prompt#
Set password interactively. See also the –no-logout option.
- -P, --password <password>#
Set password on command line. See also the –no-logout option.
- -n, --display-name <display_name>#
Set display name. defaults to the value of user_id
- -t, --threepid <threepid>#
Set a third-party identifier (email address or phone number). Pass two arguments: medium value (eg. –threepid email <user@example.org>). This option can be passed multiple times, which allows setting multiple entries for a user. When modifying existing users, all threepids are replaced by what’s passed in all given –threepid options. Threepids are used for several things: For use when logging in, as an alternative to the user id; in the case of email, as an alternative contact to help with account recovery, as well as to receive notifications of missed messages.
- --clear-threepids#
Remove all threepids of an existing user.
- -v, --avatar-url <avatar_url>#
Set avatar URL. Must be a MXC URI (https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris)
- -a, --admin, -u, --no-admin#
Grant user admin permission. Eg user is allowed to use the admin API.
- --activate#
Re-activate user.
- --deactivate#
Deactivate user. Use with caution! Deactivating a user removes their active access tokens, resets their password, kicks them out of all rooms and deletes third-party identifiers (to prevent the user requesting a password reset). See also “user deactivate” command.
- --user-type <user_type>#
Change the type of the user. Currently understood by the Admin API are ‘bot’ and ‘support’. Use ‘regular’ to create a regular Matrix user (which effectively sets the user-type to ‘null’). If the –user-type option is omitted when modifying an existing user, the user-type will not be manipulated. If the –user-type option is omitted when creating a new user, a regular user will be created.
- --no-logout#
When setting a password, the user is logged out on all devices by default (unspecified). When –no-logout is specified, devices are not logged out even when the password is changed.
- -l, --lock, -L, --unlock#
Whether to lock or unlock the account, preventing or allowing logins respectively. Feature first present in Synapse 1.91.0.
Arguments
- USER_ID#
Required argument
password#
Change a user’s password.
To prevent the user from being logged out of all sessions use option -n.
synadm user password [OPTIONS] USER_ID
Options
- -n, --no-logout#
Don’t log user out of all sessions on all devices.
- -p, --password <password>#
New password.
Arguments
- USER_ID#
Required argument
prune-devices#
Delete devices and invalidate access tokens of a user.
Deletes devices of a user and invalidates any access token associated with them. Starts from deleting the oldest devices, not seen in a number of days, which may be abandoned.
Note that this will affect the encryption and decryption of messages sent by other users to this user or to rooms where the user is present.
synadm user prune-devices [OPTIONS] USER_ID
Options
- -l, --list-only#
Dry-run: does not perform the deletion but shows what would be done. If you want to list all devices/sessions, you can also use the whois command.
- Default:
False
- -d, --min-days <min_days>#
How many days need to have passed from the last time a device was seen for it to be deleted.
- Default:
90
- -s, --min-surviving <min_surviving>#
Stop processing devices when only this number of devices is left for this user. Allows to reduce disruption by preserving recently used devices/sessions.
- Default:
1
- -i, --device-id <device_id>#
Only search devices with this ID. The other options still apply if they’re not 0.
- --datetime, --dt, --timestamp, --ts#
Display ‘last seen date/time’ in a human readable format, or as a unix timestamp in milliseconds. [default: datetime].
Arguments
- USER_ID#
Required argument
redact#
Redact events by a user, local or remote.
If a local user’s events are redacted, Synapse will act as the specified user. If a remote user’s events are redacted, Synapse will use any user with message redaction power to redact the specified remote user’s events.
synadm user redact [OPTIONS] USER_ID
Options
- -r, --room <rooms>#
Rooms to limit to for redaction. Specify this argument multiple rooms with the flag, and pass internal room IDs. Defaults to all rooms.
- --reason <reason>#
Provided reason for redaction. This will be to everyone, and will be part of the redaction event. Optional.
- -l, --limit <limit>#
Limit to amount of messages to redact. Synapse defaults to 1000.
Arguments
- USER_ID#
Required argument
redact-status#
Get the status of user events redaction.
synadm user redact-status [OPTIONS] REDACT_ID
Arguments
- REDACT_ID#
Required argument
search#
A shortcut to ‘synadm user list -d -g -n <search-term>’.
Searches for users by name/matrix-ID, including deactivated users as well as guest users. Also, compared to the original command, a case-insensitive search is done.
synadm user search [OPTIONS] SEARCH_TERM
Options
- -f, --from <from_>#
Offset user listing by given number. This option is also used for pagination.
- Default:
0
- -l, --limit <limit>#
Maximum amount of users to return.
- Default:
100
Arguments
- SEARCH_TERM#
Required argument
shadow-ban#
Shadow-ban or unban a user.
Useful for moderating malicious or egregiously abusive users.
A shadow-banned user will not receive any notification, but still will be unable to contact anyone on the server. Use this as a tool of last resort since it may lead to confusing or broken behaviour for the client.
Generally, it is more appropriate to ban or kick abusive users.
synadm user shadow-ban [OPTIONS] USER_ID
Options
- -u, --unban#
Unban the specified user
Arguments
- USER_ID#
Required argument
whois#
View information about a user’s active session.
synadm user whois [OPTIONS] USER_ID
Arguments
- USER_ID#
Required argument