User
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.
- -P, --password <password>
Set password on command line.
- -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.
- -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
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