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

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

-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>

Add a third-party identifier. This can be an email address or a phone number. 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. Format: medium value (eg. –threepid email <user@example.org>). This option can also be stated multiple times, i.e. a user can have multiple threepids configured.

-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.

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