Users
- class matterapi.endpoints.async_api.UsersApi(client: matterapi.client.base.BaseClient, skip_response_parsing: bool = False)
Endpoints for creating, getting and interacting with users.
When using endpoints that require a user id, the string me can be used in place of the user id to indicate the action is to be taken for the logged in user.
- async attach_device_id(*, json_body: Union[matterapi.models.AttachDeviceIdJsonBody, Dict]) matterapi.models.StatusOK
Attach mobile device
Attach a mobile device id to the currently logged in session. This will enable push notifications for a user, if configured by the server.
- Permissions:
Must be authenticated.
- Api Reference:
- async autocomplete_users(*, team_id: Optional[str] = None, channel_id: Optional[str] = None, name: str, limit: Optional[int] = 100) matterapi.models.UserAutocomplete
Autocomplete users
Get a list of users for the purpose of autocompleting based on the provided search term. Specify a combination of team_id and channel_id to filter results further.
- Permissions:
Requires an active session and view_team and read_channel on any teams or channels used to filter the results further.
- Api Reference:
- async check_user_mfa(*, json_body: Union[matterapi.models.CheckUserMfaJsonBody, Dict]) matterapi.models.CheckUserMfaResponse200
Check MFA
Check if a user has multi-factor authentication active on their account by providing a login id. Used to check whether an MFA code needs to be provided when logging in.
- Permissions:
No permission required.
- Api Reference:
- async convert_bot_to_user(bot_user_id: str, *, json_body: Union[matterapi.models.ConvertBotToUserJsonBody, Dict], set_system_admin: Optional[bool] = False) matterapi.models.StatusOK
Convert a bot into a user
Convert a bot into a user.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.26
- Api Reference:
- async convert_user_to_bot(user_id: str) matterapi.models.StatusOK
Convert a user into a bot
Convert a user into a bot.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.26
- Api Reference:
- async create_user(*, json_body: Union[matterapi.models.CreateUserJsonBody, Dict], t: Optional[str] = None, iid: Optional[str] = None) matterapi.models.User
Create a user
Create a new user on the system. Password is required for email login. For other authentication types such as LDAP or SAML, auth_data and auth_service fields are required.
- Permissions:
No permission required for creating email/username accounts on an open server. Auth Token is required for other authentication types such as LDAP or SAML.
- Api Reference:
- async create_user_access_token(user_id: str, *, json_body: Union[matterapi.models.CreateUserAccessTokenJsonBody, Dict]) matterapi.models.UserAccessToken
Create a user access token
Generate a user access token that can be used to authenticate with the Mattermost REST API.
- Permissions:
Must have create_user_access_token permission. For non- self requests, must also have the edit_other_users permission.
- Minimum Server Version:
4.1
- Api Reference:
- async delete_user(user_id: str) matterapi.models.StatusOK
Deactivate a user account.
Deactivates the user and revokes all its sessions by archiving its user object.
As of server version 5.28, optionally use the permanent=true query parameter to permanently delete the user for compliance reasons. To use this feature ServiceSettings.EnableAPIUserDeletion must be set to true in the server’s configuration.
- Permissions:
Must be logged in as the user being deactivated or have the edit_other_users permission.
- Api Reference:
- async demote_user_to_guest(user_id: str) matterapi.models.StatusOK
Demote a user to a guest
Convert a regular user into a guest. This will convert the user into a guest for the whole system while retaining their existing team and channel memberships.
- Permissions:
Must be logged in as the user or have the demote_to_guest permission.
- Minimum Server Version:
5.16
- Api Reference:
- async disable_user_access_token(*, json_body: Union[matterapi.models.DisableUserAccessTokenJsonBody, Dict]) matterapi.models.StatusOK
Disable personal access token
Disable a personal access token and delete any sessions using the token. The token can be re-enabled using /users/tokens/enable.
- Permissions:
Must have revoke_user_access_token permission. For non- self requests, must also have the edit_other_users permission.
- Minimum Server Version:
4.4
- Api Reference:
- async enable_user_access_token(*, json_body: Union[matterapi.models.EnableUserAccessTokenJsonBody, Dict]) matterapi.models.StatusOK
Enable personal access token
Re-enable a personal access token that has been disabled.
- Permissions:
Must have create_user_access_token permission. For non- self requests, must also have the edit_other_users permission.
- Minimum Server Version:
4.4
- Api Reference:
- async generate_mfa_secret(user_id: str) matterapi.models.GenerateMfaSecretResponse200
Generate MFA secret
Generates an multi-factor authentication secret for a user and returns it as a string and as base64 encoded QR code image.
- Permissions:
Must be logged in as the user or have the edit_other_users permission.
- Api Reference:
- async get_channel_members_with_team_data_for_user(user_id: str, *, page: Optional[int] = None, pageSize: Optional[int] = None) List[matterapi.models.ChannelMemberWithTeamData]
Get all channel members from all teams for a user
Get all channel members from all teams for a user.
- Permissions:
Logged in as the user, or have edit_other_users permission.
- Minimum Server Version:
6.2.0
- Api Reference:
- async get_default_profile_image(user_id: str) None
Return user’s default (generated) profile image
Returns the default (generated) user profile image based on user_id string parameter.
- Permissions:
Must be logged in.
- Minimum Server Version:
5.5
- Api Reference:
- async get_known_users() matterapi.models.UsersStats
Get user IDs of known users
Get the list of user IDs of users with any direct relationship with a user. That means any user sharing any channel, including direct and group channels.
- Permissions:
Must be authenticated.
- Minimum Server Version:
5.23
- Api Reference:
- async get_profile_image(user_id: str, *, _: Optional[float] = None) None
Get user’s profile image
Get a user’s profile image based on user_id string parameter.
- Permissions:
Must be logged in.
- Api Reference:
- async get_sessions(user_id: str) List[matterapi.models.Session]
Get user’s sessions
Get a list of sessions by providing the user GUID. Sensitive information will be sanitized out.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Api Reference:
- async get_total_users_stats() matterapi.models.UsersStats
Get total count of users in the system
Get a total count of users in the system.
- Permissions:
Must be authenticated.
- Api Reference:
- async get_total_users_stats_filtered(*, in_team: Optional[str] = None, in_channel: Optional[str] = None, include_deleted: Optional[bool] = None, include_bots: Optional[bool] = None, roles: Optional[str] = None, channel_roles: Optional[str] = None, team_roles: Optional[str] = None) matterapi.models.UsersStats
Get total count of users in the system matching the specified filters
Get a count of users in the system matching the specified filters.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.26
- Api Reference:
- async get_uploads_for_user(user_id: str) List[matterapi.models.UploadSession]
Get uploads for a user
Gets all the upload sessions belonging to a user.
- Permissions:
Must be logged in as the user who created the upload sessions.
- Minimum Server Version:
5.28
- Api Reference:
- async get_user(user_id: str) matterapi.models.User
Get a user
Get a user a object. Sensitive information will be sanitized out.
- Permissions:
Requires an active session but no other permissions.
- Api Reference:
- async get_user_access_token(token_id: str) matterapi.models.UserAccessTokenSanitized
Get a user access token
Get a user access token. Does not include the actual authentication token.
- Permissions:
Must have read_user_access_token permission. For non-self requests, must also have the edit_other_users permission.
- Minimum Server Version:
4.1
- Api Reference:
- async get_user_access_tokens(*, page: Optional[int] = 0, per_page: Optional[int] = 60) List[matterapi.models.UserAccessTokenSanitized]
Get user access tokens
Get a page of user access tokens for users on the system. Does not include the actual authentication tokens. Use query parameters for paging.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
4.7
- Api Reference:
- async get_user_access_tokens_for_user(user_id: str, *, page: Optional[int] = 0, per_page: Optional[int] = 60) List[matterapi.models.UserAccessTokenSanitized]
Get user access tokens
Get a list of user access tokens for a user. Does not include the actual authentication tokens. Use query parameters for paging.
- Permissions:
Must have read_user_access_token permission. For non-self requests, must also have the edit_other_users permission.
- Minimum Server Version:
4.1
- Api Reference:
- async get_user_audits(user_id: str) List[matterapi.models.Audit]
Get user’s audits
Get a list of audit by providing the user GUID.
- Permissions:
Must be logged in as the user or have the edit_other_users permission.
- Api Reference:
- async get_user_by_email(email: str) matterapi.models.User
Get a user by email
Get a user object by providing a user email. Sensitive information will be sanitized out.
- Permissions:
Requires an active session and for the current session to be able to view another user’s email based on the server’s privacy settings.
- Api Reference:
- async get_user_by_username(username: str) matterapi.models.User
Get a user by username
Get a user object by providing a username. Sensitive information will be sanitized out.
- Permissions:
Requires an active session but no other permissions.
- Api Reference:
- async get_user_terms_of_service(user_id: str) Union[matterapi.models.AppError, matterapi.models.UserTermsOfService]
Fetches user’s latest terms of service action if the latest action was for acceptance.
Will be deprecated in v6.0 Fetches user’s latest terms of service action if the latest action was for acceptance.
- Permissions:
Must be logged in as the user being acted on.
- Minimum Server Version:
5.6
- Api Reference:
- async get_users(*, page: Optional[int] = 0, per_page: Optional[int] = 60, in_team: Optional[str] = None, not_in_team: Optional[str] = None, in_channel: Optional[str] = None, not_in_channel: Optional[str] = None, in_group: Optional[str] = None, group_constrained: Optional[bool] = None, without_team: Optional[bool] = None, active: Optional[bool] = None, inactive: Optional[bool] = None, role: Optional[str] = None, sort: Optional[str] = None, roles: Optional[str] = None, channel_roles: Optional[str] = None, team_roles: Optional[str] = None) List[matterapi.models.User]
Get users
Get a page of a list of users. Based on query string parameters, select users from a team, channel, or select users not in a specific channel.
Since server version 4.0, some basic sorting is available using the sort query parameter. Sorting is currently only supported when selecting users on a team.
- Permissions:
Requires an active session and (if specified) membership to the channel or team being selected from.
- Api Reference:
- async get_users_by_group_channel_ids(*, json_body: Union[List[str], Dict]) matterapi.models.GetUsersByGroupChannelIdsResponse200
Get users by group channels ids
Get an object containing a key per group channel id in the query and its value as a list of users members of that group channel.
The user must be a member of the group ids in the query, or they will be omitted from the response.
- Permissions:
Requires an active session but no other permissions.
- Minimum Server Version:
5.14
- Api Reference:
- async get_users_by_ids(*, json_body: Union[List[str], Dict], since: Optional[int] = None) List[matterapi.models.User]
Get users by ids
Get a list of users based on a provided list of user ids.
- Permissions:
Requires an active session but no other permissions.
- Api Reference:
- async get_users_by_usernames(*, json_body: Union[List[str], Dict]) List[matterapi.models.User]
Get users by usernames
Get a list of users based on a provided list of usernames.
- Permissions:
Requires an active session but no other permissions.
- Api Reference:
- async login(*, json_body: Union[matterapi.models.LoginJsonBody, Dict]) matterapi.models.User
Login to Mattermost server
- Permissions:
No permission required
- Api Reference:
- async login_by_cws_token(*, json_body: Union[matterapi.models.LoginByCwsTokenJsonBody, Dict]) None
Auto-Login to Mattermost server using CWS token
CWS stands for Customer Web Server which is the cloud service used to manage cloud instances.
- Permissions:
A Cloud license is required
- Api Reference:
- async logout() matterapi.models.StatusOK
Logout from the Mattermost server
- Permissions:
An active session is required
- Api Reference:
- async migrate_auth_to_ldap(*, json_body: Union[matterapi.models.MigrateAuthToLdapJsonBody, Dict]) None
Migrate user accounts authentication type to LDAP.
Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to LDAP.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.28
- Api Reference:
- async migrate_auth_to_saml(*, json_body: Union[matterapi.models.MigrateAuthToSamlJsonBody, Dict]) None
Migrate user accounts authentication type to SAML.
Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to SAML.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.28
- Api Reference:
- async patch_user(user_id: str, *, json_body: Union[matterapi.models.PatchUserJsonBody, Dict]) matterapi.models.User
Patch a user
Partially update a user by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Api Reference:
- async permanent_delete_all_users() None
Permanent delete all users
Permanently deletes all users and all their related information, including posts.
- Minimum Server Version:
5.26.0
- Local Mode Only:
This endpoint is only available through [local mode](https://docs.mattermost.com/administration/mmctl-cli- tool.html#local-mode).
- Api Reference:
- async promote_guest_to_user(user_id: str) matterapi.models.StatusOK
Promote a guest to user
Convert a guest into a regular user. This will convert the guest into a user for the whole system while retaining any team and channel memberships and automatically joining them to the default channels.
- Permissions:
Must be logged in as the user or have the promote_guest permission.
- Minimum Server Version:
5.16
- Api Reference:
- async publish_user_typing(user_id: str, *, json_body: Union[matterapi.models.PublishUserTypingJsonBody, Dict]) None
Publish a user typing websocket event.
Notify users in the given channel via websocket that the given user is typing.
- Permissions:
Must have manage_system permission to publish for any user other than oneself.
- Minimum Server Version:
5.26
- Api Reference:
- async register_terms_of_service_action(user_id: str, *, json_body: Union[matterapi.models.RegisterTermsOfServiceActionJsonBody, Dict]) matterapi.models.StatusOK
Records user action when they accept or decline custom terms of service
Records user action when they accept or decline custom terms of service. Records the action in audit table. Updates user’s last accepted terms of service ID if they accepted it.
- Permissions:
Must be logged in as the user being acted on.
- Minimum Server Version:
5.4
- Api Reference:
- async reset_password(*, json_body: Union[matterapi.models.ResetPasswordJsonBody, Dict]) matterapi.models.StatusOK
Reset password
Update the password for a user using a one-use, timed recovery code tied to the user’s account. Only works for non-SSO users.
- Permissions:
No permissions required.
- Api Reference:
- async revoke_all_sessions(user_id: str) matterapi.models.StatusOK
Revoke all active sessions for a user
Revokes all user sessions from the provided user id and session id strings.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Minimum Server Version:
4.4
- Api Reference:
- async revoke_session(user_id: str, *, json_body: Union[matterapi.models.RevokeSessionJsonBody, Dict]) matterapi.models.StatusOK
Revoke a user session
Revokes a user session from the provided user id and session id strings.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Api Reference:
- async revoke_sessions_from_all_users() None
Revoke all sessions from all users.
For any session currently on the server (including admin) it will be revoked. Clients will be notified to log out users.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.14
- Api Reference:
- async revoke_user_access_token(*, json_body: Union[matterapi.models.RevokeUserAccessTokenJsonBody, Dict]) matterapi.models.StatusOK
Revoke a user access token
Revoke a user access token and delete any sessions using the token.
- Permissions:
Must have revoke_user_access_token permission. For non- self requests, must also have the edit_other_users permission.
- Minimum Server Version:
4.1
- Api Reference:
- async search_user_access_tokens(*, json_body: Union[matterapi.models.SearchUserAccessTokensJsonBody, Dict]) List[matterapi.models.UserAccessTokenSanitized]
Search tokens
Get a list of tokens based on search criteria provided in the request body. Searches are done against the token id, user id and username.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
4.7
- Api Reference:
- async search_users(*, json_body: Union[matterapi.models.SearchUsersJsonBody, Dict]) List[matterapi.models.User]
Search users
Get a list of users based on search criteria provided in the request body. Searches are typically done against username, full name, nickname and email unless otherwise configured by the server.
- Permissions:
Requires an active session and read_channel and/or view_team permissions for any channels or teams specified in the request body.
- Api Reference:
- async send_password_reset_email(*, json_body: Union[matterapi.models.SendPasswordResetEmailJsonBody, Dict]) matterapi.models.StatusOK
Send password reset email
Send an email containing a link for resetting the user’s password. The link will contain a one-use, timed recovery code tied to the user’s account. Only works for non-SSO users.
- Permissions:
No permissions required.
- Api Reference:
- async send_verification_email(*, json_body: Union[matterapi.models.SendVerificationEmailJsonBody, Dict]) matterapi.models.StatusOK
Send verification email
Send an email with a verification link to a user that has an email matching the one in the request body. This endpoint will return success even if the email does not match any users on the system.
- Permissions:
No permissions required.
- Api Reference:
- async set_default_profile_image(user_id: str) matterapi.models.StatusOK
Delete user’s profile image
Delete user’s profile image and reset to default image based on user_id string parameter.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Minimum Server Version:
5.5
- Api Reference:
- async set_profile_image(user_id: str, *, multipart_data: Union[matterapi.models.SetProfileImageMultipartData, Dict]) matterapi.models.StatusOK
Set user’s profile image
Set a user’s profile image based on user_id string parameter.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Api Reference:
- async switch_account_type(*, json_body: Union[matterapi.models.SwitchAccountTypeJsonBody, Dict]) matterapi.models.SwitchAccountTypeResponse200
Switch login method
Switch a user’s login method from using email to OAuth2/SAML/LDAP or back to email. When switching to OAuth2/SAML, account switching is not complete until the user follows the returned link and completes any steps on the OAuth2/SAML service provider.
To switch from email to OAuth2/SAML, specify current_service, new_service, email and password.
To switch from OAuth2/SAML to email, specify current_service, new_service, email and new_password.
To switch from email to LDAP/AD, specify current_service, new_service, email, password, ldap_ip and new_password (this is the user’s LDAP password).
To switch from LDAP/AD to email, specify current_service, new_service, ldap_ip, password (this is the user’s LDAP password), email and new_password.
Additionally, specify mfa_code when trying to switch an account on LDAP/AD or email that has MFA activated.
- Permissions:
No current authentication required except when switching from OAuth2/SAML to email.
- Api Reference:
- async update_user(user_id: str, *, json_body: Union[matterapi.models.UpdateUserJsonBody, Dict]) matterapi.models.User
Update a user
Update a user by providing the user object. The fields that can be updated are defined in the request body, all other provided fields will be ignored. Any fields not included in the request body will be set to null or reverted to default values.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Api Reference:
- async update_user_active(user_id: str, *, json_body: Union[matterapi.models.UpdateUserActiveJsonBody, Dict]) matterapi.models.StatusOK
Update user active status
Update user active or inactive status.
__Since server version 4.6, users using a SSO provider to login can be activated or deactivated with this endpoint. However, if their activation status in Mattermost does not reflect their status in the SSO provider, the next synchronization or login by that user will reset the activation status to that of their account in the SSO provider. Server versions 4.5 and before do not allow activation or deactivation of SSO users from this endpoint.__ User with manage_system permission can activate or deactivate a user.
- Permissions:
User can deactivate themselves.
- Api Reference:
- async update_user_auth(user_id: str, *, json_body: Union[matterapi.models.UserAuthData, Dict]) matterapi.models.UserAuthData
Update a user’s authentication method
Updates a user’s authentication method. This can be used to change them to/from LDAP authentication for example.
- Permissions:
Must have the edit_other_users permission.
- Minimum Server Version:
4.6
- Api Reference:
- async update_user_mfa(user_id: str, *, json_body: Union[matterapi.models.UpdateUserMfaJsonBody, Dict]) matterapi.models.StatusOK
Update a user’s MFA
Activates multi-factor authentication for the user if activate is true and a valid code is provided. If activate is false, then code is not required and multi-factor authentication is disabled for the user.
- Permissions:
Must be logged in as the user being updated or have the edit_other_users permission.
- Api Reference:
- async update_user_password(user_id: str, *, json_body: Union[matterapi.models.UpdateUserPasswordJsonBody, Dict]) matterapi.models.StatusOK
Update a user’s password
Update a user’s password. New password must meet password policy set by server configuration. Current password is required if you’re updating your own password.
- Permissions:
Must be logged in as the user the password is being changed for or have manage_system permission.
- Api Reference:
- async update_user_roles(user_id: str, *, json_body: Union[matterapi.models.UpdateUserRolesJsonBody, Dict]) matterapi.models.StatusOK
Update a user’s roles
Update a user’s system-level roles. Valid user roles are “system_user”, “system_admin” or both of them. Overwrites any previously assigned system-level roles.
- Permissions:
Must have the manage_roles permission.
- Api Reference:
- async verify_user_email(*, json_body: Union[matterapi.models.VerifyUserEmailJsonBody, Dict]) matterapi.models.StatusOK
Verify user email
Verify the email used by a user to sign-up their account with.
- Permissions:
No permissions required.
- Api Reference:
- async verify_user_email_without_token(user_id: str) matterapi.models.User
Verify user email by ID
Verify the email used by a user without a token.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.24
- Api Reference: