Users

Endpoints

Users

Source code in matrix_admin_sdk/endpoints/v2/users.py

class Users(Endpoint):
    async def get_all(
        self,
        user_id: Optional[str] = None,
        name: Optional[str] = None,
        guests: bool = True,
        deactivated: bool = False,
        limit: int = 100,
        from_: int = 0,
        order_by: Optional[OrderBy] = None,
        dir_: str = "f",
    ) -> UsersModel:
        order_by = OrderBy.NAME if order_by is None else order_by

        url = self.url("users")
        params = {
            "user_id": user_id,
            "name": name,
            "guests": guests,
            "deactivated": deactivated,
            "limit": limit,
            "from": from_,
            "order_by": order_by.value,
            "dir": dir_,
        }
        result = await self.request(RequestMethods.GET, url, params=params)
        res: UsersModel = UsersModel.from_dict(result)
        return res

    async def query_user_account(self, user_id: str) -> UserDetailsModel:
        """
        This API returns information about a specific user account.
        Args:
            user_id: fully-qualified user id: for example, @user:server.com

        Returns: UserDetailsModel

        """
        url = self.url(f"users/{user_id}")
        result = await self.request(RequestMethods.GET, url)
        res: UserDetailsModel = UserDetailsModel.from_dict(result)
        return res

    async def create_or_modify_account(
        self,
        user_id: str,
        password: Optional[str] = None,
        displayname: Optional[str] = None,
        avatar_url: Optional[str] = None,
        admin: bool = False,
        deactivated: bool = False,
        user_type: Optional[str] = None,
        threepids: Optional[List[Threepid]] = None,
        external_ids: Optional[List[ExternalId]] = None,
    ) -> None:
        """
        This API allows an administrator to create or modify a user account with
        a specific user_id.

        If the user already exists then optional parameters default to the current value.

        In order to re-activate an account deactivated must be set to false. If
        users do not login via single-sign-on, a new password must be provided.

        Args:
            user_id: fully-qualified user id: for example, @user:server.com.
            password:  If provided, the user's password is updated and all
                devices are logged out.
            displayname: defaults to the value of user_id.
            avatar_url: must be a MXC URI
            admin: is user an admin
            deactivated: If unspecified, deactivation state will be left unchanged
                on existing accounts and set to false for new accounts. A user cannot
                be erased by deactivating with this API. For details on deactivating
                users see Deactivate Account.
            user_type: If provided, the user type will be adjusted. If null given,
                the user type will be cleared. Other allowed options are: bot and support
            threepids: allows setting the third-party IDs (email, msisdn)
            external_ids: Allow setting the identifier of the external identity
                provider for SSO (Single sign-on). Details in Sample Configuration
                File section sso and oidc_providers

        Returns: None

        """
        if threepids is None:
            threepids = []
        if external_ids is None:
            external_ids = []
        if displayname is None:
            displayname = user_id

        threepids_list = [asdict(i) for i in threepids]
        external_ids_list = [asdict(i) for i in external_ids]

        data = {
            "displayname": displayname,
            "threepids": threepids_list,
            "external_ids": external_ids_list,
            "avatar_url": avatar_url,
            "admin": admin,
            "deactivated": deactivated,
            "user_type": user_type,
        }
        if password is not None:
            data["password"] = password

        url = self.url(f"users/{user_id}")

        await self.request(RequestMethods.PUT, url, data=data)

create_or_modify_account(self, user_id, password=None, displayname=None, avatar_url=None, admin=False, deactivated=False, user_type=None, threepids=None, external_ids=None) async

This API allows an administrator to create or modify a user account with a specific user_id.

If the user already exists then optional parameters default to the current value.

In order to re-activate an account deactivated must be set to false. If users do not login via single-sign-on, a new password must be provided.

Parameters:

Name	Type	Description	Default
user_id	str	fully-qualified user id: for example, @user:server.com.	required
password	Optional[str]	If provided, the user's password is updated and all devices are logged out.	None
displayname	Optional[str]	defaults to the value of user_id.	None
avatar_url	Optional[str]	must be a MXC URI	None
admin	bool	is user an admin	False
deactivated	bool	If unspecified, deactivation state will be left unchanged on existing accounts and set to false for new accounts. A user cannot be erased by deactivating with this API. For details on deactivating users see Deactivate Account.	False
user_type	Optional[str]	If provided, the user type will be adjusted. If null given, the user type will be cleared. Other allowed options are: bot and support	None
threepids	Optional[List[matrix_admin_sdk.endpoints.v2.users.Threepid]]	allows setting the third-party IDs (email, msisdn)	None
external_ids	Optional[List[matrix_admin_sdk.endpoints.v2.users.ExternalId]]	Allow setting the identifier of the external identity provider for SSO (Single sign-on). Details in Sample Configuration File section sso and oidc_providers	None

Source code in matrix_admin_sdk/endpoints/v2/users.py

async def create_or_modify_account(
    self,
    user_id: str,
    password: Optional[str] = None,
    displayname: Optional[str] = None,
    avatar_url: Optional[str] = None,
    admin: bool = False,
    deactivated: bool = False,
    user_type: Optional[str] = None,
    threepids: Optional[List[Threepid]] = None,
    external_ids: Optional[List[ExternalId]] = None,
) -> None:
    """
    This API allows an administrator to create or modify a user account with
    a specific user_id.

    If the user already exists then optional parameters default to the current value.

    In order to re-activate an account deactivated must be set to false. If
    users do not login via single-sign-on, a new password must be provided.

    Args:
        user_id: fully-qualified user id: for example, @user:server.com.
        password:  If provided, the user's password is updated and all
            devices are logged out.
        displayname: defaults to the value of user_id.
        avatar_url: must be a MXC URI
        admin: is user an admin
        deactivated: If unspecified, deactivation state will be left unchanged
            on existing accounts and set to false for new accounts. A user cannot
            be erased by deactivating with this API. For details on deactivating
            users see Deactivate Account.
        user_type: If provided, the user type will be adjusted. If null given,
            the user type will be cleared. Other allowed options are: bot and support
        threepids: allows setting the third-party IDs (email, msisdn)
        external_ids: Allow setting the identifier of the external identity
            provider for SSO (Single sign-on). Details in Sample Configuration
            File section sso and oidc_providers

    Returns: None

    """
    if threepids is None:
        threepids = []
    if external_ids is None:
        external_ids = []
    if displayname is None:
        displayname = user_id

    threepids_list = [asdict(i) for i in threepids]
    external_ids_list = [asdict(i) for i in external_ids]

    data = {
        "displayname": displayname,
        "threepids": threepids_list,
        "external_ids": external_ids_list,
        "avatar_url": avatar_url,
        "admin": admin,
        "deactivated": deactivated,
        "user_type": user_type,
    }
    if password is not None:
        data["password"] = password

    url = self.url(f"users/{user_id}")

    await self.request(RequestMethods.PUT, url, data=data)

query_user_account(self, user_id) async

This API returns information about a specific user account.

Parameters:

Name	Type	Description	Default
user_id	str	fully-qualified user id: for example, @user:server.com	required

Source code in matrix_admin_sdk/endpoints/v2/users.py

async def query_user_account(self, user_id: str) -> UserDetailsModel:
    """
    This API returns information about a specific user account.
    Args:
        user_id: fully-qualified user id: for example, @user:server.com

    Returns: UserDetailsModel

    """
    url = self.url(f"users/{user_id}")
    result = await self.request(RequestMethods.GET, url)
    res: UserDetailsModel = UserDetailsModel.from_dict(result)
    return res

Models

UsersModel

List of users

Attributes:

Name	Type	Description
users	list[UserModel]	List of users
total	int	total number of users
next_token	str|None	next token

Source code in matrix_admin_sdk/models/v2/users.py

class UsersModel(BaseModel):
    """
    List of users
    Attributes:
        users (list[UserModel]): List of users
        total (int): total number of users
        next_token (str|None): next token

    """

    users: List[UserModel]
    total: int
    next_token: Optional[str] = None

    @classmethod
    def from_dict(cls, data: Dict[str, Any]):
        users = [UserModel.from_dict(i) for i in data["users"]]
        return cls(users=users, total=data["total"], next_token=data.get("next_token"))

UserModel

User model

Attributes:

Name	Type	Description
name	str	Fully-qualified user ID (ex. @user:server.com).
is_guest	bool	Status if that user is a guest account.
admin	bool	Status if that user is an admin account.
deactivated	bool	Status if that user has been marked as deactivated.
shadow_banned	bool	Status if that user has been marked as shadow banned.
displayname	str|None	The user's display name if they have set one.
creation_ts	int	The user's creation timestamp in ms.
avatar_url	str|None	he user's avatar URL if they have set one
user_type	str|None	Type of the user. Normal users are type None. This allows user type specific behaviour. There are also types support and bot

Source code in matrix_admin_sdk/models/v2/users.py

class UserModel(BaseModel):
    """
    User model
    Attributes:
        name (str): Fully-qualified user ID (ex. @user:server.com).
        is_guest (bool): Status if that user is a guest account.
        admin (bool): Status if that user is an admin account.
        deactivated (bool): Status if that user has been marked as deactivated.
        shadow_banned (bool): Status if that user has been marked as shadow banned.
        displayname (str|None): The user's display name if they have set one.
        creation_ts (int): The user's creation timestamp in ms.
        avatar_url (str|None): he user's avatar URL if they have set one
        user_type (str|None): Type of the user. Normal users are type None.
            This allows user type specific behaviour. There are also types support and bot
    """

    name: str
    is_guest: bool
    admin: bool
    deactivated: bool
    shadow_banned: bool
    creation_ts: int
    displayname: Optional[str]
    avatar_url: Optional[str]
    user_type: Optional[str]

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "UserModel":
        displayname = data.get("displayname")
        avatar_url = data.get("avatar_url")
        user_type = data.get("user_type")
        return cls(
            name=data["name"],
            is_guest=data["is_guest"],
            admin=data["admin"],
            deactivated=data["deactivated"],
            shadow_banned=data["shadow_banned"],
            creation_ts=data["creation_ts"],
            displayname=displayname,
            avatar_url=avatar_url,
            user_type=user_type,
        )

UserDetailsModel

UserDetailsModel(name: str, is_guest: bool, admin: bool, deactivated: bool, shadow_banned: bool, creation_ts: int, displayname: Union[str, NoneType], avatar_url: Union[str, NoneType], user_type: Union[str, NoneType], threepids: List[matrix_admin_sdk.models.v2.users.ThreepidModel], appservice_id: Union[str, NoneType], consent_server_notice_sent: Union[str, NoneType], consent_version: Union[str, NoneType], external_ids: List[matrix_admin_sdk.models.v2.users.ExternalId])

Source code in matrix_admin_sdk/models/v2/users.py

class UserDetailsModel(UserModel):
    threepids: List[ThreepidModel]
    appservice_id: Optional[str]
    consent_server_notice_sent: Optional[str]
    consent_version: Optional[str]
    external_ids: List[ExternalId]

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "UserDetailsModel":
        user_data = asdict(UserModel.from_dict(data))
        user_data["threepids"] = [
            ThreepidModel.from_dict(i) for i in data.get("threepids", [])
        ]
        user_data["external_ids"] = [
            ExternalId.from_dict(i) for i in data.get("external_ids", [])
        ]
        user_data["consent_server_notice_sent"] = data.get(
            "consent_server_notice_sent", None
        )
        user_data["consent_version"] = data.get("consent_version", None)
        user_data["appservice_id"] = data.get("appservice_id", None)
        return cls(**user_data)

ExternalId

ExternalId(auth_provider: str, external_id: str)

Source code in matrix_admin_sdk/models/v2/users.py

class ExternalId(BaseModel):
    auth_provider: str
    external_id: str

ThreepidModel

ThreepidModel(medium: str, address: str, added_at: int, validated_at: int)

Source code in matrix_admin_sdk/models/v2/users.py

class ThreepidModel(BaseModel):
    medium: str
    address: str
    added_at: int
    validated_at: int