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

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