/api/v4/users/login: post: tags: - users summary: Login to Mattermost server description: > ##### Permissions No permission required operationId: Login requestBody: content: application/json: schema: type: object properties: id: type: string login_id: type: string token: type: string device_id: type: string ldap_only: type: boolean password: description: The password used for email authentication. type: string magic_link_token: description: Magic link token for passwordless guest authentication. When provided, authenticates the user using the magic link token instead of password. Requires guest magic link feature to be enabled. type: string description: User authentication object required: true responses: "201": description: User login successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/login/cws: post: tags: - users summary: Auto-Login to Mattermost server using CWS token description: > CWS stands for Customer Web Server which is the cloud service used to manage cloud instances. ##### Permissions A Cloud license is required operationId: LoginByCwsToken requestBody: content: application/json: schema: type: object properties: login_id: type: string cws_token: type: string description: User authentication object required: true responses: "302": description: Login successful, it'll redirect to login page to perform the autologin "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/login/sso/code-exchange: post: tags: - users summary: Exchange SSO login code for session tokens description: > Exchange a short-lived login_code for session tokens using SAML code exchange (mobile SSO flow). This endpoint is part of the mobile SSO code-exchange flow to prevent tokens from appearing in deep links. ##### Permissions No permission required. operationId: LoginSSOCodeExchange requestBody: content: application/json: schema: type: object required: - login_code - code_verifier - state properties: login_code: description: Short-lived one-time code from SSO callback type: string code_verifier: description: SAML verifier to prove code possession type: string state: description: State parameter to prevent CSRF attacks type: string description: SSO code exchange object required: true responses: "200": description: Code exchange successful content: application/json: schema: type: object properties: token: description: Session token for authentication type: string csrf: description: CSRF token for request validation type: string "400": $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" /oauth/intune: post: tags: - users summary: Login with Microsoft Intune MAM description: > Authenticate a mobile user using a Microsoft Entra ID (Azure AD) access token for Intune Mobile Application Management (MAM) protected apps. This endpoint enables authentication for mobile apps protected by Microsoft Intune MAM policies. The access token is obtained via the Microsoft Authentication Library (MSAL) and validated against the configured Azure AD tenant and Intune MAM app registration. **Authentication Flow:** 1. Mobile app acquires an Entra ID access token via MSAL with the Intune MAM scope 2. Token is sent to this endpoint for validation 3. Server validates the token signature, claims, and tenant configuration 4. User is authenticated or created based on the token claims 5. Session token is returned for subsequent API requests **User Provisioning:** - **Office365 AuthService**: Users are automatically created on first login using the `oid` (Azure AD object ID) claim as the unique identifier - **SAML AuthService**: Users must first login via web/desktop to establish their account with the `oid` (Azure AD object ID) as AuthData. Intune MAM always uses objectId for SAML users. For Entra ID Domain Services LDAP sync, configure LdapSettings.IdAttribute to `msDS-aadObjectId` to ensure consistency. **Error Handling:** This endpoint returns specific HTTP status codes to help mobile apps handle different error scenarios: - `428 Precondition Required`: SAML user needs to login via web/desktop first - `403 Forbidden`: Configuration issues or bot accounts - `409 Conflict`: User account is deactivated - `401 Unauthorized`: Token has expired - `400 Bad Request`: Invalid token format, claims, or configuration ##### Permissions No permission required. Authentication is performed via the Entra ID access token. ##### Enterprise Feature Requires Mattermost Enterprise Advanced license and proper Intune MAM configuration (tenant ID, client ID, and auth service). operationId: LoginIntune requestBody: content: application/json: schema: $ref: "#/components/schemas/IntuneLoginRequest" description: Intune login credentials containing the Entra ID access token required: true responses: "200": description: User authentication successful content: application/json: schema: $ref: "#/components/schemas/User" "400": description: > Bad request - Invalid token format, signature, claims, or configuration. Common causes include: invalid JSON body, missing access_token, malformed JWT, invalid token issuer/audience/tenant, missing required claims (oid, email), or empty auth data after extraction. content: application/json: schema: $ref: "#/components/schemas/AppError" "401": description: Unauthorized - The Entra ID access token has expired content: application/json: schema: $ref: "#/components/schemas/AppError" "403": description: > Forbidden - Access denied. Common causes include: Intune MAM not properly configured or enabled, or user is a bot account (bots cannot use Intune login). content: application/json: schema: $ref: "#/components/schemas/AppError" "409": description: Conflict - User account has been deactivated (DeleteAt != 0) content: application/json: schema: $ref: "#/components/schemas/AppError" "428": description: > Precondition Required - SAML user account not found. The user must first login via web or desktop application to establish their Mattermost account with objectId as AuthData before using mobile Intune MAM authentication. For Entra ID Domain Services LDAP sync, ensure SamlSettings.IdAttribute references the objectidentifier claim and LdapSettings.IdAttribute is set to 'msDS-aadObjectId'. content: application/json: schema: $ref: "#/components/schemas/AppError" "500": description: > Internal Server Error - Server-side error. Common causes include: failed to initialize JWKS (JSON Web Key Set) from Microsoft's OpenID configuration, or failed to create user session. content: application/json: schema: $ref: "#/components/schemas/AppError" "501": description: > Not Implemented - Intune MAM feature is not available. This occurs when running Mattermost Team Edition or when enterprise features are not loaded. content: application/json: schema: $ref: "#/components/schemas/AppError" /api/v4/users/logout: post: tags: - users summary: Logout from the Mattermost server description: > ##### Permissions An active session is required operationId: Logout responses: "201": description: User logout successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" /api/v4/users: post: tags: - users summary: Create a user description: > 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. operationId: CreateUser parameters: - name: t in: query description: Token id from an email invitation required: false schema: type: string - name: iid in: query description: Token id from an invitation link required: false schema: type: string requestBody: content: application/json: schema: type: object required: - email - username properties: email: type: string username: type: string first_name: type: string last_name: type: string nickname: type: string position: type: string timezone: $ref: "#/components/schemas/Timezone" auth_data: description: Service-specific authentication data, such as email address. type: string auth_service: description: The authentication service, one of "email", "gitlab", "ldap", "saml", "office365", "google", and "". type: string password: description: The password used for email authentication. type: string locale: type: string props: type: object notify_props: $ref: "#/components/schemas/UserNotifyProps" description: User object to be created required: true responses: "201": description: User creation successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" get: tags: - users summary: Get users description: > 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. Some fields, like `email_verified` and `notify_props`, are only visible for the authorized user or if the authorized user has the `manage_system` permission. ##### Permissions Requires an active session and (if specified) membership to the channel or team being selected from. operationId: GetUsers parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of users per page. schema: type: integer default: 60 - name: in_team in: query description: The ID of the team to get users for. schema: type: string - name: not_in_team in: query description: The ID of the team to exclude users for. Must not be used with "in_team" query parameter. schema: type: string - name: in_channel in: query description: The ID of the channel to get users for. schema: type: string - name: not_in_channel in: query description: The ID of the channel to exclude users for. Must be used with "in_channel" query parameter. schema: type: string - name: in_group in: query description: The ID of the group to get users for. Must have `manage_system` permission. schema: type: string - name: group_constrained in: query description: When used with `not_in_channel` or `not_in_team`, returns only the users that are allowed to join the channel or team based on its group constrains. schema: type: boolean - name: without_team in: query description: Whether or not to list users that are not on any team. This option takes precendence over `in_team`, `in_channel`, and `not_in_channel`. schema: type: boolean - name: active in: query description: Whether or not to list only users that are active. This option cannot be used along with the `inactive` option. schema: type: boolean - name: inactive in: query description: Whether or not to list only users that are deactivated. This option cannot be used along with the `active` option. schema: type: boolean - name: role in: query description: Returns users that have this role. schema: type: string - name: sort in: query description: > Sort is only available in conjunction with certain options below. The paging parameter is also always available. ##### `in_team` Can be "", "last_activity_at" or "create_at". When left blank, sorting is done by username. Note that when "last_activity_at" is specified, an additional "last_activity_at" field will be returned in the response packet. __Minimum server version__: 4.0 ##### `in_channel` Can be "", "status". When left blank, sorting is done by username. `status` will sort by User's current status (Online, Away, DND, Offline), then by Username. __Minimum server version__: 4.7 ##### `in_group` Can be "", "display_name". When left blank, sorting is done by username. `display_name` will sort alphabetically by user's display name. __Minimum server version__: 7.7 schema: type: string - name: roles in: query description: > Comma separated string used to filter users based on any of the specified system roles Example: `?roles=system_admin,system_user` will return users that are either system admins or system users __Minimum server version__: 5.26 schema: type: string - name: channel_roles in: query description: > Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with `in_channel` Example: `?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user` will return users that are only channel users and not admins or guests __Minimum server version__: 5.26 schema: type: string - name: team_roles in: query description: > Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with `in_team` Example: `?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user` will return users that are only team users and not admins or guests __Minimum server version__: 5.26 schema: type: string responses: "200": description: User page retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" delete: tags: - users summary: Permanent delete all users description: > 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). operationId: PermanentDeleteAllUsers responses: "200": description: Delete request was successful /api/v4/users/ids: post: tags: - users summary: Get users by ids description: | Get a list of users based on a provided list of user ids. ##### Permissions Requires an active session but no other permissions. operationId: GetUsersByIds parameters: - name: since in: query description: > Only return users that have been modified since the given Unix timestamp (in milliseconds). __Minimum server version__: 5.14 schema: type: integer requestBody: content: application/json: schema: type: array items: type: string description: List of user ids required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" /api/v4/users/group_channels: post: tags: - users summary: Get users by group channels ids description: | 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 operationId: GetUsersByGroupChannelIds requestBody: content: application/json: schema: type: array items: type: string description: List of group channel ids required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: object properties: : type: array items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" /api/v4/users/usernames: post: tags: - users summary: Get users by usernames description: | Get a list of users based on a provided list of usernames. ##### Permissions Requires an active session but no other permissions. operationId: GetUsersByUsernames requestBody: content: application/json: schema: type: array items: type: string description: List of usernames required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" /api/v4/users/search: post: tags: - users summary: Search users description: > 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. operationId: SearchUsers requestBody: content: application/json: schema: type: object required: - term properties: term: description: The term to match against username, full name, nickname and email type: string team_id: description: If provided, only search users on this team type: string not_in_team_id: description: If provided, only search users not on this team type: string in_channel_id: description: If provided, only search users in this channel type: string not_in_channel_id: description: If provided, only search users not in this channel. Must specifiy `team_id` when using this option type: string in_group_id: description: If provided, only search users in this group. Must have `manage_system` permission. type: string group_constrained: description: When used with `not_in_channel_id` or `not_in_team_id`, returns only the users that are allowed to join the channel or team based on its group constrains. type: boolean allow_inactive: description: When `true`, include deactivated users in the results type: boolean without_team: type: boolean description: Set this to `true` if you would like to search for users that are not on a team. This option takes precendence over `team_id`, `in_channel_id`, and `not_in_channel_id`. limit: description: > The maximum number of users to return in the results __Available as of server version 5.6. Defaults to `100` if not provided or on an earlier server version.__ type: integer default: 100 description: Search criteria required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/autocomplete: get: tags: - users summary: Autocomplete users description: > 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. operationId: AutocompleteUsers parameters: - name: team_id in: query description: Team ID schema: type: string - name: channel_id in: query description: Channel ID schema: type: string - name: name in: query description: Username, nickname first name or last name required: true schema: type: string - name: limit in: query description: > The maximum number of users to return in each subresult __Available as of server version 5.6. Defaults to `100` if not provided or on an earlier server version.__ schema: type: integer default: 100 responses: "200": description: User autocomplete successful content: application/json: schema: $ref: "#/components/schemas/UserAutocomplete" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/known: get: tags: - users summary: Get user IDs of known users description: | 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 operationId: GetKnownUsers responses: "200": description: Known users' IDs retrieval successful content: application/json: schema: type: array $ref: "#/components/schemas/KnownUsers" "401": $ref: "#/components/responses/Unauthorized" /api/v4/users/stats: get: tags: - users summary: Get total count of users in the system description: | Get a total count of users in the system. ##### Permissions Must be authenticated. operationId: GetTotalUsersStats responses: "200": description: User stats retrieval successful content: application/json: schema: $ref: "#/components/schemas/UsersStats" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /api/v4/users/stats/filtered: get: tags: - users summary: Get total count of users in the system matching the specified filters description: | Get a count of users in the system matching the specified filters. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: GetTotalUsersStatsFiltered parameters: - name: in_team in: query description: The ID of the team to get user stats for. schema: type: string - name: in_channel in: query description: The ID of the channel to get user stats for. schema: type: string - name: include_deleted in: query description: If deleted accounts should be included in the count. schema: type: boolean - name: include_bots in: query description: If bot accounts should be included in the count. schema: type: boolean - name: roles in: query description: > Comma separated string used to filter users based on any of the specified system roles Example: `?roles=system_admin,system_user` will include users that are either system admins or system users schema: type: string - name: channel_roles in: query description: > Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with `in_channel` Example: `?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user` will include users that are only channel users and not admins or guests schema: type: string - name: team_roles in: query description: > Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with `in_team` Example: `?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user` will include users that are only team users and not admins or guests schema: type: string responses: "200": description: Filtered User stats retrieval successful content: application/json: schema: $ref: "#/components/schemas/UsersStats" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}": get: tags: - users summary: Get a user description: | Get a user a object. Sensitive information will be sanitized out. ##### Permissions Requires an active session but no other permissions. operationId: GetUser parameters: - name: user_id in: path description: User GUID. This can also be "me" which will point to the current user. required: true schema: type: string responses: "200": description: User retrieval successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" put: tags: - users summary: Update a user description: > 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. operationId: UpdateUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id - email - username properties: id: type: string email: type: string username: type: string first_name: type: string last_name: type: string nickname: type: string locale: type: string position: type: string timezone: $ref: "#/components/schemas/Timezone" props: type: object notify_props: $ref: "#/components/schemas/UserNotifyProps" description: User object that is to be updated required: true responses: "200": description: User update successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" delete: tags: - users summary: Deactivate a user account. description: > 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. operationId: DeleteUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User deactivation successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/patch": put: tags: - users summary: Patch a user description: > 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. operationId: PatchUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: email: type: string username: type: string first_name: type: string last_name: type: string nickname: type: string locale: type: string position: type: string timezone: $ref: "#/components/schemas/Timezone" props: type: object notify_props: $ref: "#/components/schemas/UserNotifyProps" description: User object that is to be updated required: true responses: "200": description: User patch successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/roles": put: tags: - users summary: Update a user's roles description: > 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. operationId: UpdateUserRoles parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - roles properties: roles: type: string description: Space-delimited system roles to assign to the user required: true responses: "200": description: User roles update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/active": put: tags: - users summary: Activate or deactivate a user description: > Activate or deactivate a user's account. A deactivated user can't log into Mattermost or use it without being reactivated. __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.__ ##### Permissions User can deactivate themselves. User with `manage_system` permission can activate or deactivate a user. operationId: UpdateUserActive parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - active properties: active: type: boolean description: Use `true` to activate the user or `false` to deactivate them required: true responses: "200": description: User activation/deactivation update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/image": get: tags: - users summary: Get user's profile image description: | Get a user's profile image based on user_id string parameter. ##### Permissions Must be logged in. operationId: GetProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: _ in: query description: Not used by the server. Clients can pass in the last picture update time of the user to potentially take advantage of caching required: false schema: type: number responses: "200": description: User's profile image "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" post: tags: - users summary: Set user's profile image description: > 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. operationId: SetProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: image: description: The image to be uploaded type: string format: binary required: - image responses: "200": description: Profile image set successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" delete: tags: - users summary: Delete user's profile image description: > 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 operationId: SetDefaultProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Profile image reset successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/image/default": get: tags: - users summary: Return user's default (generated) profile image description: > Returns the default (generated) user profile image based on user_id string parameter. ##### Permissions Must be logged in. __Minimum server version__: 5.5 operationId: GetDefaultProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Default profile image "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/username/{username}": get: tags: - users summary: Get a user by username description: > Get a user object by providing a username. Sensitive information will be sanitized out. ##### Permissions Requires an active session but no other permissions. operationId: GetUserByUsername parameters: - name: username in: path description: Username required: true schema: type: string responses: "200": description: User retrieval successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" /api/v4/users/password/reset: post: tags: - users summary: Reset password description: > 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. operationId: ResetPassword requestBody: content: application/json: schema: type: object required: - code - new_password properties: code: description: The recovery code type: string new_password: description: The new password for the user type: string required: true responses: "200": description: User password update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/mfa": put: tags: - users summary: Update a user's MFA description: > 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. operationId: UpdateUserMfa parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - activate properties: activate: description: Use `true` to activate, `false` to deactivate type: boolean code: description: The code produced by your MFA client. Required if `activate` is true type: string required: true responses: "200": description: User MFA update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/mfa/generate": post: tags: - users summary: Generate MFA secret description: > 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. operationId: GenerateMfaSecret parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: MFA secret generation successful content: application/json: schema: type: object properties: secret: description: The MFA secret as a string type: string qr_code: description: A base64 encoded QR code image type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/demote": post: tags: - users summary: Demote a user to a guest description: | 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. __Minimum server version__: 5.16 ##### Permissions Must be logged in as the user or have the `demote_to_guest` permission. operationId: DemoteUserToGuest parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User successfully demoted content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/promote": post: tags: - users summary: Promote a guest to user description: | 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. __Minimum server version__: 5.16 ##### Permissions Must be logged in as the user or have the `promote_guest` permission. operationId: PromoteGuestToUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Guest successfully promoted content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/convert_to_bot": post: tags: - bots - users summary: Convert a user into a bot description: | Convert a user into a bot. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: ConvertUserToBot parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User successfully converted content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /api/v4/users/mfa: post: tags: - users summary: Check MFA description: > 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. operationId: CheckUserMfa requestBody: content: application/json: schema: type: object required: - login_id properties: login_id: description: The email or username used to login type: string required: true responses: "200": description: MFA check successful content: application/json: schema: type: object properties: mfa_required: description: Value will `true` if MFA is active, `false` otherwise type: boolean "400": $ref: "#/components/responses/BadRequest" "/api/v4/users/{user_id}/password": put: tags: - users summary: Update a user's password description: > 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. operationId: UpdateUserPassword parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - new_password properties: current_password: description: The current password for the user type: string new_password: description: The new password for the user type: string required: true responses: "200": description: User password update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/password/reset/send: post: tags: - users summary: Send password reset email description: > 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. operationId: SendPasswordResetEmail requestBody: content: application/json: schema: type: object required: - email properties: email: description: The email of the user type: string required: true responses: "200": description: Email sent if account exists content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/email/{email}": get: tags: - users summary: Get a user by email description: > 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. operationId: GetUserByEmail parameters: - name: email in: path description: User Email required: true schema: type: string responses: "200": description: User retrieval successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/sessions": get: tags: - users summary: Get user's sessions description: > 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. operationId: GetSessions parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User session retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Session" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/sessions/revoke": post: tags: - users summary: Revoke a user session description: > 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. operationId: RevokeSession parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - session_id properties: session_id: description: The session GUID to revoke. type: string required: true responses: "200": description: User session revoked successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/sessions/revoke/all": post: tags: - users summary: Revoke all active sessions for a user description: > 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 operationId: RevokeAllSessions parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User sessions revoked successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/sessions/device: put: tags: - users summary: Attach mobile device and extra props to the session object description: > Attach extra props to the session object of the currently logged in session. Adding a mobile device id will enable push notifications for a user, if configured by the server. Other props are also available, like whether the device has notifications disabled and the mobile version. ##### Permissions Must be authenticated. operationId: AttachDeviceExtraProps requestBody: content: application/json: schema: type: object properties: device_id: description: Mobile device id. For Android prefix the id with `android:` and Apple with `apple:` type: string deviceNotificationDisabled: description: Whether the mobile device has notifications disabled. Accepted values are "true" or "false". type: string mobileVersion: description: Mobile app version. The version must be parseable as a semver. type: string required: true responses: "200": description: Device id attach successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "/api/v4/users/{user_id}/audits": get: tags: - users summary: Get user's audits description: | 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. operationId: GetUserAudits parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User audits retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Audit" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/email/verify/member": post: tags: - users summary: Verify user email by ID description: | Verify the email used by a user without a token. __Minimum server version__: 5.24 ##### Permissions Must have `manage_system` permission. operationId: VerifyUserEmailWithoutToken parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User email verification successful content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" /api/v4/users/email/verify: post: tags: - users summary: Verify user email description: | Verify the email used by a user to sign-up their account with. ##### Permissions No permissions required. operationId: VerifyUserEmail requestBody: content: application/json: schema: type: object required: - token properties: token: description: The token given to validate the email type: string required: true responses: "200": description: User email verification successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" /api/v4/users/email/verify/send: post: tags: - users summary: Send verification email description: > 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. operationId: SendVerificationEmail requestBody: content: application/json: schema: type: object required: - email properties: email: description: Email of a user type: string required: true responses: "200": description: Email send successful if email exists content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" /api/v4/users/login/switch: post: tags: - users summary: Switch login method description: > 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. operationId: SwitchAccountType requestBody: content: application/json: schema: type: object required: - current_service - new_service properties: current_service: description: The service the user currently uses to login type: string new_service: description: The service the user will use to login type: string email: description: The email of the user type: string password: description: The password used with the current service type: string mfa_code: description: The MFA code of the current service type: string ldap_id: description: The LDAP/AD id of the user type: string required: true responses: "200": description: Login method switch or request successful content: application/json: schema: type: object properties: follow_link: description: The link for the user to follow to login or to complete the account switching when the current service is OAuth2/SAML type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" /api/v4/users/login/type: post: tags: - users summary: Get login authentication type description: > 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. For this version, the endpoint only returns a non-empty `auth_service` if the user has magic_link enabled. For all other authentication methods (email/password, OAuth, SAML, LDAP), an empty string is returned. ##### Permissions No permission required operationId: GetLoginType requestBody: content: application/json: schema: type: object properties: id: description: The user ID (optional, can be used with login_id) type: string login_id: description: The login ID (email, username, or unique identifier) type: string device_id: description: The device ID for audit logging purposes type: string description: Login type request object required: true responses: "200": description: Login type retrieved successfully content: application/json: schema: type: object properties: auth_service: description: The authentication service type. Returns the actual service type if guest_magic_link is enabled (in which case a magic link is also sent to the user's email). Returns an empty string for all other authentication methods. type: string "400": $ref: "#/components/responses/BadRequest" "/api/v4/users/{user_id}/tokens": post: tags: - users summary: Create a user access token description: > Generate a user access token that can be used to authenticate with the Mattermost REST API. __Minimum server version__: 4.1 ##### Permissions Must have `create_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: CreateUserAccessToken parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - description properties: description: description: A description of the token usage type: string required: true responses: "201": description: User access token creation successful content: application/json: schema: $ref: "#/components/schemas/UserAccessToken" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" get: tags: - users summary: Get user access tokens description: > Get a list of user access tokens for a user. Does not include the actual authentication tokens. Use query parameters for paging. __Minimum server version__: 4.1 ##### Permissions Must have `read_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: GetUserAccessTokensForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of tokens per page. schema: type: integer default: 60 responses: "200": description: User access tokens retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/UserAccessTokenSanitized" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/tokens: get: tags: - users summary: Get user access tokens description: > Get a page of user access tokens for users on the system. Does not include the actual authentication tokens. Use query parameters for paging. __Minimum server version__: 4.7 ##### Permissions Must have `manage_system` permission. operationId: GetUserAccessTokens parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of tokens per page. schema: type: integer default: 60 responses: "200": description: User access tokens retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/UserAccessTokenSanitized" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/tokens/revoke: post: tags: - users summary: Revoke a user access token description: > Revoke a user access token and delete any sessions using the token. __Minimum server version__: 4.1 ##### Permissions Must have `revoke_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: RevokeUserAccessToken requestBody: content: application/json: schema: type: object required: - token_id properties: token_id: description: The user access token GUID to revoke type: string required: true responses: "200": description: User access token revoke successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/tokens/{token_id}": get: tags: - users summary: Get a user access token description: > Get a user access token. Does not include the actual authentication token. __Minimum server version__: 4.1 ##### Permissions Must have `read_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: GetUserAccessToken parameters: - name: token_id in: path description: User access token GUID required: true schema: type: string responses: "200": description: User access token retrieval successful content: application/json: schema: $ref: "#/components/schemas/UserAccessTokenSanitized" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /api/v4/users/tokens/disable: post: tags: - users summary: Disable personal access token description: > Disable a personal access token and delete any sessions using the token. The token can be re-enabled using `/users/tokens/enable`. __Minimum server version__: 4.4 ##### Permissions Must have `revoke_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: DisableUserAccessToken requestBody: content: application/json: schema: type: object required: - token_id properties: token_id: description: The personal access token GUID to disable type: string required: true responses: "200": description: Personal access token disable successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/tokens/enable: post: tags: - users summary: Enable personal access token description: > Re-enable a personal access token that has been disabled. __Minimum server version__: 4.4 ##### Permissions Must have `create_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: EnableUserAccessToken requestBody: content: application/json: schema: type: object required: - token_id properties: token_id: description: The personal access token GUID to enable type: string required: true responses: "200": description: Personal access token enable successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/users/tokens/search: post: tags: - users summary: Search tokens description: > 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. __Minimum server version__: 4.7 ##### Permissions Must have `manage_system` permission. operationId: SearchUserAccessTokens requestBody: content: application/json: schema: type: object required: - term properties: term: description: The search term to match against the token id, user id or username. type: string description: Search criteria required: true responses: "200": description: Personal access token search successful content: application/json: schema: type: array items: $ref: "#/components/schemas/UserAccessTokenSanitized" "/api/v4/users/{user_id}/auth": put: tags: - users summary: Update a user's authentication method description: > Updates a user's authentication method. This can be used to change them to/from LDAP authentication for example. __Minimum server version__: 4.6 ##### Permissions Must have the `edit_other_users` permission. operationId: UpdateUserAuth parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UserAuthData" required: true responses: "200": description: User auth update successful content: application/json: schema: $ref: "#/components/schemas/UserAuthData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/terms_of_service": post: tags: - users - terms of service summary: Records user action when they accept or decline custom terms of service description: > 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. __Minimum server version__: 5.4 ##### Permissions Must be logged in as the user being acted on. operationId: RegisterTermsOfServiceAction parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - serviceTermsId - accepted properties: serviceTermsId: description: terms of service ID on which the user is acting on type: string accepted: description: true or false, indicates whether the user accepted or rejected the terms of service. type: string description: terms of service details required: true responses: "200": description: Terms of service action recorded successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" get: tags: - users - terms of service summary: Fetches user's latest terms of service action if the latest action was for acceptance. description: > Will be deprecated in v6.0 Fetches user's latest terms of service action if the latest action was for acceptance. __Minimum server version__: 5.6 ##### Permissions Must be logged in as the user being acted on. operationId: GetUserTermsOfService parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User's accepted terms of service action content: application/json: schema: $ref: "#/components/schemas/UserTermsOfService" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": description: User hasn't performed an action or the latest action was a rejection. content: application/json: schema: $ref: "#/components/schemas/AppError" /api/v4/users/sessions/revoke/all: post: tags: - users summary: Revoke all sessions from all users. description: > For any session currently on the server (including admin) it will be revoked. Clients will be notified to log out users. __Minimum server version__: 5.14 ##### Permissions Must have `manage_system` permission. operationId: RevokeSessionsFromAllUsers responses: "200": description: Sessions successfully revoked. "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/typing": post: tags: - users summary: Publish a user typing websocket event. description: > Notify users in the given channel via websocket that the given user is typing. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission to publish for any user other than oneself. operationId: PublishUserTyping parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - channel_id properties: channel_id: description: The id of the channel to which to direct the typing event. type: string parent_id: description: The optional id of the root post of the thread to which the user is replying. If unset, the typing event is directed at the entire channel. type: string responses: '200': description: User typing websocket event accepted for publishing. '400': $ref: "#/components/responses/BadRequest" '401': $ref: "#/components/responses/Unauthorized" '403': $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/uploads": get: tags: - users summary: Get uploads for a user description: | Gets all the upload sessions belonging to a user. __Minimum server version__: 5.28 ##### Permissions Must be logged in as the user who created the upload sessions. operationId: GetUploadsForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string responses: "200": description: User's uploads retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/UploadSession" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/channel_members": get: tags: - users summary: Get all channel members from all teams for a user description: | Get all channel members from all teams for a user. __Minimum server version__: 6.2.0 ##### Permissions Logged in as the user, or have `edit_other_users` permission. operationId: GetChannelMembersWithTeamDataForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: page in: query description: Page specifies which part of the results to return, by perPage. required: false schema: type: integer - name: per_page in: query description: The size of the returned chunk of results. schema: type: integer default: 60 responses: "200": description: User's uploads retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelMemberWithTeamData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" /api/v4/users/migrate_auth/ldap: post: tags: - users - migrate - authentication - LDAP summary: Migrate user accounts authentication type to LDAP. description: > Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to LDAP. __Minimum server version__: 5.28 ##### Permissions Must have `manage_system` permission. operationId: MigrateAuthToLdap requestBody: content: application/json: schema: type: object required: - from - match_field - force properties: from: description: The current authentication type for the matched users. type: string match_field: description: Foreign user field name to match. type: string force: type: boolean responses: '200': description: Successfully migrated authentication type to LDAP. '400': $ref: "#/components/responses/BadRequest" '401': $ref: "#/components/responses/Unauthorized" '403': $ref: "#/components/responses/Forbidden" '501': $ref: "#/components/responses/NotImplemented" /api/v4/users/migrate_auth/saml: post: tags: - users - migrate - authentication - SAML summary: Migrate user accounts authentication type to SAML. description: > Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to SAML. __Minimum server version__: 5.28 ##### Permissions Must have `manage_system` permission. operationId: MigrateAuthToSaml requestBody: content: application/json: schema: type: object required: - from - matches - auto properties: from: description: The current authentication type for the matched users. type: string matches: description: Users map. type: object auto: type: boolean responses: '200': description: Successfully migrated authentication type to LDAP. '400': $ref: "#/components/responses/BadRequest" '401': $ref: "#/components/responses/Unauthorized" '403': $ref: "#/components/responses/Forbidden" '501': $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/teams/{team_id}/threads": get: tags: - threads summary: Get all threads that user is following description: | Get all threads that user is following __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: GetUserThreads parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: since in: query description: Since filters the threads based on their LastUpdateAt timestamp. required: false schema: type: integer - name: deleted in: query description: Deleted will specify that even deleted threads should be returned (For mobile sync). required: false schema: type: boolean default: false - name: extended in: query description: Extended will enrich the response with participant details. required: false schema: type: boolean default: false - name: page in: query description: Page specifies which part of the results to return, by per_page. required: false schema: type: integer default: 0 - name: per_page in: query description: The size of the returned chunk of results. schema: type: integer default: 60 - name: totalsOnly in: query description: Setting this to true will only return the total counts. required: false schema: type: boolean default: false - name: threadsOnly in: query description: Setting this to true will only return threads. required: false schema: type: boolean default: false responses: "200": description: User's thread retrieval successful content: application/json: schema: $ref: "#/components/schemas/UserThreads" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/threads/mention_counts": get: tags: - threads summary: Get all unread mention counts from followed threads, per-channel description: | Get all unread mention counts from followed threads __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: GetThreadMentionCountsByChannel parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string responses: "200": description: Get was successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/threads/read": put: tags: - threads summary: Mark all threads that user is following as read description: | Mark all threads that user is following as read __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: UpdateThreadsReadForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}/read/{timestamp}": put: tags: - threads summary: Mark a thread that user is following read state to the timestamp description: | Mark a thread that user is following as read __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: UpdateThreadReadForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to update required: true schema: type: string - name: timestamp in: path description: The timestamp to which the thread's "last read" state will be reset. required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}/set_unread/{post_id}": post: tags: - threads summary: Mark a thread that user is following as unread based on a post id description: | Mark a thread that user is following as unread __Minimum server version__: 6.7 ##### Permissions Must have `read_channel` permission for the channel the thread is in or if the channel is public, have the `read_public_channels` permission for the team. Must have `edit_other_users` permission if the user is not the one marking the thread for himself. operationId: SetThreadUnreadByPostId parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to update required: true schema: type: string - name: post_id in: path description: The ID of a post belonging to the thread to mark as unread. required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}/following": put: tags: - threads summary: Start following a thread description: | Start following a thread __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: StartFollowingThread parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to follow required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" delete: tags: - threads summary: Stop following a thread description: | Stop following a thread __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: StopFollowingThread parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to update required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}": get: tags: - threads summary: Get a thread followed by the user description: | Get a thread __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: GetUserThread parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to follow required: true schema: type: string responses: "200": description: Get was successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/data_retention/team_policies": get: tags: - data retention summary: Get the policies which are applied to a user's teams description: | Gets the policies which are applied to the all of the teams to which a user belongs. __Minimum server version__: 5.35 ##### Permissions Must be logged in as the user or have the `manage_system` permission. ##### License Requires an E20 license. operationId: GetTeamPoliciesForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of policies per page. schema: type: integer default: 60 responses: "200": description: Teams for retention policy successfully retrieved. content: application/json: schema: $ref: "#/components/schemas/RetentionPolicyForTeamList" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/data_retention/channel_policies": get: tags: - data retention summary: Get the policies which are applied to a user's channels description: | Gets the policies which are applied to the all of the channels to which a user belongs. __Minimum server version__: 5.35 ##### Permissions Must be logged in as the user or have the `manage_system` permission. ##### License Requires an E20 license. operationId: GetChannelPoliciesForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of policies per page. schema: type: integer default: 60 responses: "200": description: Channels for retention policy successfully retrieved. content: application/json: schema: $ref: "#/components/schemas/RetentionPolicyForChannelList" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/NotImplemented" /api/v4/users/invalid_emails: get: tags: - users summary: Get users with invalid emails description: > Get users whose emails are considered invalid. It is an error to invoke this API if your team settings enable an open server. ##### Permissions Requires `sysconsole_read_user_management_users`. operationId: GetUsersWithInvalidEmails parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of users per page. schema: type: integer default: 60 responses: "200": description: User page retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/reset_failed_attempts": post: tags: - users summary: Reset the failed password attempts for a user description: | Reset the FailedAttempts field for a user to 0. This will only work for ldap and email/password users. ##### Permissions Requires `sysconsole_write_user_management_users` permission. operationId: resetPasswordFailedAttempts responses: "200": description: User's thread update successful "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound"