mirror of
https://github.com/mattermost/mattermost.git
synced 2025-02-25 18:55:24 -06:00
3259 lines
99 KiB
YAML
3259 lines
99 KiB
YAML
/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
|
|
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/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.
|
|
|
|
##### 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:
|
|
<CHANNEL_ID>:
|
|
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: Update user active status
|
|
description: >
|
|
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.__
|
|
|
|
##### 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 set the user active, `false` for inactive
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: User active status 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
|
|
description: >
|
|
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.
|
|
operationId: AttachDeviceId
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- device_id
|
|
properties:
|
|
device_id:
|
|
description: Mobile device id. For Android prefix the id with `android:`
|
|
and Apple with `apple:`
|
|
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/{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"
|