Synadm Package

The synadm package contains the synadm.api module which is responsible for accessing the Synapse admin API endpoints and the regular Matrix API endpoints. Also some helper methods, e.g to calculate time-related things are to be found in this module:

Synapse admin API and regular Matrix API clients

Most API calls defined in this module respect the API’s defaults and only pass what’s necessary in the request body.

A fully qualified Matrix user ID looks like this: @user:server, where server often is a domain name only, e.g @user@example.org

See https://github.com/matrix-org/synapse/tree/master/docs/admin_api for documentation of the Synapse admin APIs and the Matrix spec at https://matrix.org/docs/spec/#matrix-apis.

class synadm.api.ApiRequest(log, user, token, base_url, path, timeout, debug)

Bases: object

Basic API request handling and helper utilities

This is subclassed by SynapseAdmin and Matrix

query(method, urlpart, params=None, data=None, token=None)

Generic wrapper around requests methods

Handles requests methods, logging and exceptions

Parameters

  • urlpart (string) – the path to the API endpoint, excluding self.base_url and self.path (the part after proto://fqdn:port/path).

  • params (dict, optional) – URL parameters (?param1&paarm2). Defaults to None.

  • data (dict, optional) – request body used in POST, PUT, DELETE requests. Defaults to None.

Returns

usually a JSON string containing

the response of the API; responses that are not 200(OK) (usally error messages returned by the API) will also be returned as JSON strings; on exceptions the error type and description are logged and None is returned.

Return type

string or None

_timestamp_from_days_ago(days)

Get a unix timestamp in ms from days ago

Parameters

days (int) – number of days

Returns

a unix timestamp in milliseconds (ms)

Return type

int

_timestamp_from_days_ahead(days)

Get a unix timestamp in ms for the given number of days ahead

Parameters

days (int) – number of days

Returns

a unix timestamp in milliseconds (ms)

Return type

int

_timestamp_from_datetime(_datetime)

Get a unix timestamp in ms from a datetime object

Parameters

_datetime (datetime object) – an object built by datetime.datetime

Returns

a unix timestamp in milliseconds (ms)

Return type

int

_datetime_from_timestamp(timestamp)

Get a datetime object from a unix timestamp in ms

Parameters

timestamp (int) – a unix timestamp in milliseconds (ms)

Returns

an object built by datetime.datetime

Return type

datetime object

class synadm.api.Matrix(log, user, token, base_url, matrix_path, timeout, debug)

Bases: synadm.api.ApiRequest

Matrix API client

Inheritance:
ApiRequest (object): parent class containing general properties and

methods for requesting REST API’s

user_login(user_id, password)

Login as a Matrix user and retrieve an access token

Parameters

  • user_id (string) – a fully qualified Matrix user ID

  • password (string) – the Matrix user’s password

Returns

JSON string containing a token suitable to access the

Matrix API on the user’s behalf, a device_id and some more details on Matrix server and user.

Return type

string

raw_request(endpoint, method, data, token=None)
class synadm.api.SynapseAdmin(log, user, token, base_url, admin_path, timeout, debug)

Bases: synadm.api.ApiRequest

Synapse admin API client

Inheritance:
ApiRequest (object): parent class containing general properties and

methods for requesting REST API’s

user_list(_from, _limit, _guests, _deactivated, _name, _user_id)

List and search users

Parameters

  • _from (int) – offsets user list by this number, used for pagination

  • _limit (int) – maximum number of users returned, used for pagination

  • _guests (bool) – enable/disable fetching of guest users

  • _deactivated (bool) – enable/disable fetching of deactivated users

  • _name (string) – user name localpart to search for, see Synapse admin API docs for details

  • _user_id (string) – fully qualified Matrix user ID to search for

Returns

JSON string containing the found users

Return type

string

user_membership(user_id)

Get a list of rooms the given user is member of

Parameters

user_id (string) – fully qualified Matrix user ID

Returns

JSON string containing the admin API’s response or None if

an exception occured. See Synapse admin API docs for details.

Return type

string

user_deactivate(user_id, gdpr_erase)

Delete a given user

Parameters

  • user_id (string) – fully qualified Matrix user ID

  • gdpr_erase (bool) – enable/disable gdpr-erasing the user, see Synapse admin API docs for details.

Returns

JSON string containing the admin API’s response or None if

an exception occured. See Synapse admin API docs for details.

Return type

string

user_password(user_id, password, no_logout)

Set the user password, and log the user out if requested

Parameters

  • user_id (string) – fully qualified Matrix user ID

  • password (string) – new password that should be set

  • no_logout (bool) – the API defaults to logging out the user after password reset via the admin API, this option can be used to disable this behaviour.

Returns

JSON string containing the admin API’s response or None if an exception occured. See Synapse admin API docs for details.

Return type

string

user_details(user_id)

Get information about a given user

Note that the admin API docs describe this function as “Query User Account”.

Parameters

user_id (string) – fully qualified Matrix user ID

Returns

JSON string containing the admin API’s response or None if

an exception occured. See Synapse admin API docs for details.

Return type

string

user_login(user_id, expire_days, expire, _expire_ts)

Get an access token that can be used to authenticate as that user.

If one of the args expire_days, expire or _expire_ts is set, the valid_until_ms field will be sent to the API endpoint. If this is not the case the default of the API would be used. At the time of writing, this would be that tokens never expire.

Note: If this method is called by the CLI frontend code (synadm.cli.user.user_login_cmd), a default expiry date of 1 day (24h) is passed.

Parameters

  • user_id (string) – fully qualified Matrix user ID

  • expire_days (int) – token should expire after this number of days

  • expire (datetime) – token should expire after this date/time - a datetime object (e.g. as generated by Click.DateTime())

  • _expire_ts (int) – token should expire after this date/time - a unix timestamp in ms.

Returns

JSON string containing the admin API’s response or None if an exception occured. See Synapse admin API docs for details.

Return type

string

user_modify(user_id, password, display_name, threepid, avatar_url, admin, deactivation)

Create or update information about a given user

Threepid should be passed as a tuple in a tuple

user_whois(user_id)

Return information about the active sessions for a specific user

room_join(room_id_or_alias, user_id)

Allow an administrator to join an user account with a given user_id to a room with a given room_id_or_alias

room_list(_from, limit, name, order_by, reverse)

List and search rooms

room_details(room_id)

Get details about a room

room_members(room_id)

Get a list of room members

room_delete(room_id, new_room_user_id, room_name, message, block, no_purge)

Delete a room and purge it if requested

room_make_admin(room_id, user_id)

Grant a user room admin permission. If the user is not in the room, and it is not publicly joinable, then invite the user.

room_media_list(room_id)

Get a list of known media in an (unencrypted) room.

media_quarantine(server_name, media_id)

Quarantine a single piece of local or remote media

room_media_quarantine(room_id)

Quarantine all local and remote media in a room

user_media_quarantine(user_id)

Quarantine all local and remote media of a user

user_media(user_id, _from, limit, order_by, reverse)

Get a user’s uploaded media

media_delete(server_name, media_id)

Delete a specific (local) media_id

media_delete_by_date_or_size(server_name, before_days, before, _before_ts, _size_gt, delete_profiles)

Delete local media by date and/or size FIXME and/or?

media_protect(media_id)

Protect a single piece of local or remote media

from being quarantined

purge_media_cache(before_days, before, _before_ts)

Purge old cached remote media

version()

Get the server version

group_delete(group_id)

Delete a local group (community)

purge_history(room_id, before_event_id, before_days, before, _before_ts, delete_local)

Purge room history

purge_history_status(purge_id)

Get status of a recent history purge

The status will be one of active, complete, or failed.