users
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.
Login to Mattermost server
##### Permissions
Login using desktop token
Login to Mattermost with a short-lived desktop token.
Auto-Login to Mattermost server using CWS token
CWS stands for Customer Web Server which is the cloud service used to manage cloud instances.
Exchange SSO login code for session tokens
Exchange a short-lived login_code for session tokens using SAML code exchange (mobile SSO flow).
Login with Microsoft Intune MAM
Authenticate a mobile user using a Microsoft Entra ID (Azure AD) access token for Intune Mobile Application Management (MAM) protected apps.
Logout from the Mattermost server
##### Permissions
Save notify-admin intent
Save a notify-admin request for upgrade or trial flows.
Trigger notify-admin posts
Trigger admin notification posts manually when enabled by configuration.
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.
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.
Permanent delete all users
Permanently deletes all users and all their related information, including posts.
Get users by ids
Get a list of users based on a provided list of user ids.
Get users by group channels ids
Get an object containing a key per group channel id in the
Get users by usernames
Get a list of users based on a provided list of usernames.
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.
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.
Get user IDs of known users
Get the list of user IDs of users with any direct relationship with a
Get total count of users in the system
Get a total count of users in the system.
Get total count of users in the system matching the specified filters
Get a count of users in the system matching the specified filters.
Get a user
Get a user a object. Sensitive information will be sanitized out.
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.
Deactivate a user account.
Deactivates the user and revokes all its sessions by archiving its user object.
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.
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.
Activate or deactivate a user
Activate or deactivate a user's account. A deactivated user can't log into Mattermost or use it without being reactivated.
Get user's profile image
Get a user's profile image based on user_id string parameter.
Set user's profile image
Set a user's profile image based on user_id string parameter.
Delete user's profile image
Delete user's profile image and reset to default image based on user_id string parameter.
Return user's default (generated) profile image
Returns the default (generated) user profile image based on user_id string parameter.
Get a user by username
Get a user object by providing a username. Sensitive information will be sanitized out.
Get a user by auth data
Get a user by their external auth data identifier. The `value` is matched against what is stored in `Users.AuthData`, which for most identity providers is the identifier as the provider issues it.
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.
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.
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.
Demote a user to a guest
Convert a regular user into a guest. This will convert the user into a
Promote a guest to user
Convert a guest into a regular user. This will convert the guest into a
Convert a user into a bot
Convert a user into a bot.
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.
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.
Get a user by email
Get a user object by providing a user email. Sensitive information will be sanitized out.
Get user's sessions
Get a list of sessions by providing the user GUID. Sensitive information will be sanitized out.
Revoke a user session
Revokes a user session from the provided user id and session id strings.
Revoke all active sessions for a user
Revokes all user sessions from the provided user id and session id strings.
Attach mobile device and extra props to the session object
Attach extra props to the session object of the currently logged in session.
Get the session attributes manifest
Get the set of session attributes the server expects the client to collect, filtered to the requesting client's platform, including the per-attribute TTL and grace period.
Get user's audits
Get a list of audit by providing the user GUID.
Verify user email by ID
Verify the email used by a user without a token.
Verify user email
Verify the email used by a user to sign-up their account with.
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.
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.
Get login authentication type
Get the authentication service type (auth_service) for a user to determine how they should authenticate. This endpoint is typically used in the login flow to determine which authentication method to use.
Create a user access token
Generate a user access token that can be used to authenticate with the Mattermost REST API.
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.
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.
Revoke a user access token
Revoke a user access token and delete any sessions using the token.
Count non-compliant personal access tokens
Count the active personal access tokens that violate the configured `ServiceSettings.MaximumPersonalAccessTokenLifetimeDays` policy (tokens that never expire or expire beyond the cap). Bot account tokens are exempt and never counted. Returns 0 when no maximum lifetime is configured.
Revoke non-compliant personal access tokens
Revoke (hard-delete) every active personal access token that violates the configured `ServiceSettings.MaximumPersonalAccessTokenLifetimeDays` policy, along with any sessions created from them, and return the number of tokens revoked. Bot account tokens are exempt. The request is rejected with 400 when no maximum lifetime is configured, since there is nothing to revoke. This is irreversible; use `/users/tokens/non_compliant/count` first to preview the blast radius.
Get a user access token
Get a user access token. Does not include the actual authentication token.
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`.
Enable personal access token
Re-enable a personal access token that has been disabled.
Rotate a personal access token
Generate a new secret for an existing personal access token, immediately invalidating the old secret and any sessions that used it. The response includes the new token secret (shown once, like token creation).
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.
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.
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.
Fetches user's latest terms of service action if the latest action was for acceptance.
Will be deprecated in v6.0
Revoke all sessions from all users.
For any session currently on the server (including admin) it will be revoked.
Publish a user typing websocket event.
Notify users in the given channel via websocket that the given user is typing.
Get uploads for a user
Gets all the upload sessions belonging to a user.
Get all channel members from all teams for a user
Get all channel members from all teams for a user.
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.
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.
Upsert synced draft
Create or update a synced draft for the current user.
Get synced drafts for a team
Get synced drafts for the current user in a team.
Delete synced draft
Delete a synced draft for a channel.
Delete synced thread draft
Delete a synced draft for a channel thread.
Get users with invalid emails
Get users whose emails are considered invalid.
Reset the failed password attempts for a user
Reset the FailedAttempts field for a user to 0. This will only work for ldap and email/password users.
Convert a bot into a user
Convert a bot into a user.
Gets the server limits for the server
Gets the server limits for the server