Download OpenAPI specification:Download
There is also a work-in-progress Postman API reference.
The Mattermost Web Services API is used by Mattermost clients and third party applications to interact with the server. JavaScript and Golang drivers for connecting to the APIs are also available.
Mattermost core committers work with the community to keep the API documentation up-to-date.
If you have questions on API routes not listed in this reference, please join the Mattermost community server to ask questions in the Developers channel, or post questions to our Developer Discussion forum.
Bug reports in the documentation or the API are also welcome, as are pull requests to fix the issues.
When you have answers to API questions not addressed in our documentation we ask you to consider making a pull request to improve our reference. Small changes and larger changes are all welcome.
We also have Help Wanted tickets available for community members who would like to help others more easily use the APIs. We acknowledge everyone's contribution in the release notes of our next version.
The source code for this API reference is hosted at https://github.com/mattermost/mattermost-api-reference.
All API access is through HTTP(S) requests at your-mattermost-url.com/api/v4
. All request and response bodies are application/json
.
When using endpoints that require a user id, the string me
can be used in place of the user id to indicate the action is to be taken for the logged in user.
Since Mattermost 4.6 released on January 16, 2018, API v3 has no longer been supported and it will be removed in Mattermost Server v5.0 on June 16, 2018. Follow these simple steps to migrate your integrations and apps to API v4. Otherwise your integrations may break once you upgrade to Mattermost 5.0
DEBUG
in System Console > General > Logging > File Log Level to print detailed logs for API requests./api/v3/
endpoints. Any requests hitting these endpoints are from integrations that should be migrated to API v4.DEBUG
. Confirm no requests hit /api/v3/
endpoints.false
in System Console > General > Configuration, or set EnableAPIv3
to false
in config.json
. This setting disables API v3 on your server. Any time a v3 endpoint is used, an error is logged in System Console > Logs.ERROR
. Use the error logs to help track down any remaining uses of API v3.Below are the major changes made between v3 and v4:
If you have any questions about the API v3 deprecation, or about migrating from v3 to v4, join our daily build server at pre-release.mattermost.com and ask questions in the APIv4 channel.
The easiest way to interact with the Mattermost Web Service API is through a language specific driver.
For other community-built drivers and API wrappers, see our app directory.
There are multiple ways to authenticate against the Mattermost API.
All examples assume there is a Mattermost instance running at http://localhost:8065.
Make an HTTP POST to your-mattermost-url.com/api/v4/users/login
with a JSON body indicating the user’s login_id
, password
and optionally the MFA token
. The login_id
can be an email, username or an AD/LDAP ID depending on the system's configuration.
curl -i -d '{"login_id":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v4/users/login
NOTE: If you're running cURL on windows, you will have to change the single quotes to double quotes, and escape the inner double quotes with backslash, like below:
curl -i -d "{\"login_id\":\"someone@nowhere.com\",\"password\":\"thisisabadpassword\"}" http://localhost:8065/api/v4/users/login
If successful, the response will contain a Token
header and a user object in the body.
HTTP/1.1 200 OK
Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly
Token: hyr5dmb1mbb49c44qmx4whniso
X-Ratelimit-Limit: 10
X-Ratelimit-Remaining: 9
X-Ratelimit-Reset: 1
X-Request-Id: smda55ckcfy89b6tia58shk5fh
X-Version-Id: developer
Date: Fri, 11 Sep 2015 13:21:14 GMT
Content-Length: 657
Content-Type: application/json; charset=utf-8
{{user object as json}}
Include the Token
as part of the Authorization
header on your future API requests with the Bearer
method.
curl -i -H 'Authorization: Bearer hyr5dmb1mbb49c44qmx4whniso' http://localhost:8065/api/v4/users/me
You should now be able to access the API as the user you logged in as.
Using personal access tokens is very similar to using a session token. The only real difference is that session tokens will expire, while personal access tokens will live until they are manually revoked by the user or an admin.
Just like session tokens, include the personal access token as part of the Authorization
header in your requests using the Bearer
method. Assuming our personal access token is 9xuqwrwgstrb3mzrxb83nb357a
, we could use it as shown below.
curl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me
Mattermost has the ability to act as an OAuth 2.0 service provider.
The official documentation for using your Mattermost server as an OAuth 2.0 service provider can be found here.
For an example on how to register an OAuth 2.0 app with your Mattermost instance, please see the Mattermost-Zapier integration documentation.
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
Must have manage_system
permission.
from required | string The current authentication type for the matched users. |
match_field required | string Foreign user field name to match. |
force required | boolean |
Successfully migrated authentication type to LDAP.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Feature is disabled
{- "from": "string",
- "match_field": "string",
- "force": true
}
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
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
Must have manage_system
permission.
from required | string The current authentication type for the matched users. |
matches required | object Users map. |
auto required | boolean |
Successfully migrated authentication type to LDAP.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Feature is disabled
{- "from": "string",
- "matches": { },
- "auto": true
}
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
All errors will return an appropriate HTTP response code along with the following JSON body:
{
"id": "the.error.id",
"message": "Something went wrong", // the reason for the error
"request_id": "", // the ID of the request
"status_code": 0, // the HTTP status code
"is_oauth": false // whether the error is OAuth specific
}
Whenever you make an HTTP request to the Mattermost API you might notice the following headers included in the response:
X-Ratelimit-Limit: 10
X-Ratelimit-Remaining: 9
X-Ratelimit-Reset: 1441983590
These headers are telling you your current rate limit status.
Header | Description |
---|---|
X-Ratelimit-Limit | The maximum number of requests you can make per second. |
X-Ratelimit-Remaining | The number of requests remaining in the current window. |
X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets. |
If you exceed your rate limit for a window you will receive the following error in the body of the response:
HTTP/1.1 429 Too Many Requests
Date: Tue, 10 Sep 2015 11:20:28 GMT
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1
limit exceeded
In addition to the HTTP RESTful web service, Mattermost also offers a WebSocket event delivery system and some API functionality.
To connect to the WebSocket follow the standard opening handshake as defined by the RFC specification to the /api/v4/websocket
endpoint of Mattermost.
The Mattermost WebSocket can be authenticated by cookie or through an authentication challenge. If you're authenticating from a browser and have logged in with the Mattermost API, your authentication cookie should already be set, this is how the Mattermost webapp authenticates with the WebSocket.
To authenticate with an authentication challenge, first connect the WebSocket and then send the following JSON over the connection:
{
"seq": 1,
"action": "authentication_challenge",
"data": {
"token": "mattermosttokengoeshere"
}
}
If successful, you will receive a standard OK response over the WebSocket connection:
{
"status": "OK",
"seq_reply": 1
}
Once successfully authenticated, the server will pass a hello
WebSocket event containing server version over the connection.
WebSocket events are primarily used to alert the client to changes in Mattermost, such as delivering new posts or alerting the client that another user is typing in a channel.
Events on the WebSocket will have the form:
{
"event": "hello",
"data": {
"server_version": "3.6.0.1451.1c38da627ebb4e3635677db6939e9195"
},
"broadcast":{
"omit_users": null,
"user_id": "ay5sq51sebfh58ktrce5ijtcwy",
"channel_id": "",
"team_id": ""
},
"seq": 0
}
The event
field indicates the event type, data
contains any data relevant to the event and broadcast
contains information about who the event was sent to. For example, the above example has user_id
set to "ay5sq51sebfh58ktrce5ijtcwy" meaning that only the user with that ID received this event broadcast. The omit_users
field can contain an array of user IDs that were specifically omitted from receiving the event.
The list of Mattermost WebSocket events are:
Mattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection:
{
"action": "user_typing",
"seq": 2,
"data": {
"channel_id": "nhze199c4j87ped4wannrjdt9c",
"parent_id": ""
}
}
This is an example of making a user_typing
request, with the purpose of alerting the server that the connected client has begun typing in a channel or thread. The action
field indicates what is being requested, and performs a similar duty as the route in a HTTP API.
The seq
or sequence number is set by the client and should be incremented with every use. It is used to distinguish responses to requests that come down the WebSocket. For example, a standard response to the above request would be:
{
"status": "OK",
"seq_reply": 2
}
Notice seq_reply
is 2, matching the seq
of the original request. Using this a client can distinguish which request the response is meant for.
If there was any information to respond with, it would be encapsulated in a data
field.
In the case of an error, the response would be:
{
"status": "FAIL",
"seq_reply": 2,
"error": {
"id": "some.error.id.here",
"message": "Some error message here"
}
}
The list of WebSocket API actions is:
To see how these actions work, please refer to either the Golang WebSocket driver or our JavaScript WebSocket driver.
Endpoints for creating, getting and interacting with users.
When using endpoints that require a user id, the string me
can be used in place of the user id to indicate the action is to be taken for the logged in user.
No permission required
User authentication object
id | string |
login_id | string |
token | string |
device_id | string |
ldap_only | boolean |
password | string The password used for email authentication. |
User login successful
Invalid or missing parameters in URL or request body
Do not have appropriate permissions
{- "id": "string",
- "login_id": "string",
- "token": "string",
- "device_id": "string",
- "ldap_only": true,
- "password": "string"
}
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
CWS stands for Customer Web Server which is the cloud service used to manage cloud instances.
A Cloud license is required
User authentication object
login_id | string |
cws_token | string |
Login successful, it'll redirect to login page to perform the autologin
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "login_id": "string",
- "cws_token": "string"
}
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
An active session is required
User logout successful
Invalid or missing parameters in URL or request body
Do not have appropriate permissions
{- "status": "string"
}
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.
No permission required but user creation can be controlled by server configuration.
t | string Token id from an email invitation |
iid | string Token id from an invitation link |
User object to be created
email required | string |
username required | string |
first_name | string |
last_name | string |
nickname | string |
auth_data | string Service-specific authentication data, such as email address. |
auth_service | string The authentication service, one of "email", "gitlab", "ldap", "saml", "office365", "google", and "". |
password | string The password used for email authentication. |
locale | string |
props | object |
notify_props | object (UserNotifyProps) |
User creation successful
Invalid or missing parameters in URL or request body
Do not have appropriate permissions
{- "email": "string",
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "auth_data": "string",
- "auth_service": "string",
- "password": "string",
- "locale": "string",
- "props": { },
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}
}
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
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.
Requires an active session and (if specified) membership to the channel or team being selected from.
page | integer Default: 0 The page to select. |
per_page | integer Default: 60 The number of users per page. There is a maximum limit of 200 users per page. |
in_team | string The ID of the team to get users for. |
not_in_team | string The ID of the team to exclude users for. Must not be used with "in_team" query parameter. |
in_channel | string The ID of the channel to get users for. |
not_in_channel | string The ID of the channel to exclude users for. Must be used with "in_channel" query parameter. |
in_group | string The ID of the group to get users for. Must have |
group_constrained | boolean When used with |
without_team | boolean Whether or not to list users that are not on any team. This option takes precendence over |
active | boolean Whether or not to list only users that are active. This option cannot be used along with the |
inactive | boolean Whether or not to list only users that are deactivated. This option cannot be used along with the |
role | string Returns users that have this role. |
sort | string Sort is only available in conjunction with certain options below. The paging parameter is also always available.
|
roles | string Comma separated string used to filter users based on any of the specified system roles Example: Minimum server version: 5.26 |
channel_roles | string Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with Example: Minimum server version: 5.26 |
team_roles | string Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with Example: Minimum server version: 5.26 |
User page retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") // page, perPage, etag users := Client.GetUsers(0, 60, "") users = Client.GetUsersInChannel("channelid", 0, 60, "") users = Client.GetUsersNotInChannel("teamid", "channelid", 0, 60, "") users = Client.GetUsersInTeam("teamid", 0, 60, "") users = Client.GetUsersNotInTeam("teamid", 0, 60, "") users = Client.GetUsersWithoutTeam(0, 60, "")
[- {
- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
]
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.
Delete request was successful
import ( "net" "net/http" "github.com/mattermost/mattermost-server/v5/model" ) tr := &http.Transport{ Dial: func(network, addr string) (net.Conn, error) { return net.Dial("unix", socketPath) }, } Client := model.NewAPIv4Client("http://_") Client.HttpClient = &http.Client{Transport: tr} ok, resp := Client.PermanentDeleteAllUsers()
Get a list of users based on a provided list of user ids.
Requires an active session but no other permissions.
since | integer Only return users that have been modified since the given Unix timestamp (in milliseconds). Minimum server version: 5.14 |
List of user ids
User list retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
[- "string"
]
[- {
- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
]
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.
Requires an active session but no other permissions.
Minimum server version: 5.14
List of group channel ids
User list retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
[- "string"
]
{- "<CHANNEL_ID>": [
- {
- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
]
}
Get a list of users based on a provided list of usernames.
Requires an active session but no other permissions.
List of usernames
User list retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
[- "string"
]
[- {
- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
]
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.
Requires an active session and read_channel
and/or view_team
permissions for any channels or teams specified in the request body.
Search criteria
term required | string The term to match against username, full name, nickname and email |
team_id | string If provided, only search users on this team |
not_in_team_id | string If provided, only search users not on this team |
in_channel_id | string If provided, only search users in this channel |
not_in_channel_id | string If provided, only search users not in this channel. Must specifiy |
in_group_id | string If provided, only search users in this group. Must have |
group_constrained | boolean When used with |
allow_inactive | boolean When |
without_team | boolean Set this to |
limit | integer Default: 100 The maximum number of users to return in the results Available as of server version 5.6. Defaults to |
User list retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "term": "string",
- "team_id": "string",
- "not_in_team_id": "string",
- "in_channel_id": "string",
- "not_in_channel_id": "string",
- "in_group_id": "string",
- "group_constrained": true,
- "allow_inactive": true,
- "without_team": true,
- "limit": 100
}
[- {
- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
]
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.
Requires an active session and view_team
and read_channel
on any teams or channels used to filter the results further.
team_id | string Team ID |
channel_id | string Channel ID |
name required | string Username, nickname first name or last name |
limit | integer Default: 100 The maximum number of users to return in each subresult Available as of server version 5.6. Defaults to |
User autocomplete successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") teamID := "4xp9fdt77pncbef59f4k1qe83o" channelID := "Ej3SKOHlWIKAblkUTK5Xvkj2cm" username := "testUsername" users, resp := Client.AutocompleteUsersInChannel(teamID, channelID, username, 100, "")
{- "users": [
- {
- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
], - "out_of_channel": [
- {
- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
]
}
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.
Must be authenticated.
Minimum server version: 5.23
Known users' IDs retrieval successful
No access token provided
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userIds, resp := Client.GetKnownUsers()
{- "total_users_count": 0
}
Get a total count of users in the system.
Must be authenticated.
User stats retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") stats, resp := Client.GetTotalUsersStats("")
{- "total_users_count": 0
}
Get a count of users in the system matching the specified filters.
Minimum server version: 5.26
Must have manage_system
permission.
in_team | string The ID of the team to get user stats for. |
in_channel | string The ID of the channel to get user stats for. |
include_deleted | boolean If deleted accounts should be included in the count. |
include_bots | boolean If bot accounts should be included in the count. |
roles | string Comma separated string used to filter users based on any of the specified system roles Example: |
channel_roles | string Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with Example: |
team_roles | string Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with Example: |
Filtered User stats retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
{- "total_users_count": 0
}
Get a user a object. Sensitive information will be sanitized out.
Requires an active session but no other permissions.
user_id required | string User GUID. This can also be "me" which will point to the current user. |
User retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "4xp9fdt77pncbef59f4k1qe83o" user, resp := Client.GetUser(userID, "")
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
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.
Must be logged in as the user being updated or have the edit_other_users
permission.
user_id required | string User GUID |
User object that is to be updated
id required | string |
string | |
username | string |
first_name | string |
last_name | string |
nickname | string |
locale | string |
position | string |
props | object |
notify_props | object (UserNotifyProps) |
User update successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "id": "string",
- "email": "string",
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "locale": "string",
- "position": "string",
- "props": { },
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}
}
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
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.
Must be logged in as the user being deactivated or have the edit_other_users
permission.
user_id required | string User GUID |
User deactivation successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "4xp9fdt77pncbef59f4k1qe83o" ok, resp := Client.DeleteUser(userID)
{- "status": "string"
}
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.
Must be logged in as the user being updated or have the edit_other_users
permission.
user_id required | string User GUID |
User object that is to be updated
string | |
username | string |
first_name | string |
last_name | string |
nickname | string |
locale | string |
position | string |
props | object |
notify_props | object (UserNotifyProps) |
User patch successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "email": "string",
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "locale": "string",
- "position": "string",
- "props": { },
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}
}
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
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.
Must have the manage_roles
permission.
user_id required | string User GUID |
Space-delimited system roles to assign to the user
roles required | string |
User roles update successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "roles": "string"
}
{- "status": "string"
}
Update user active or inactive status.
Since server version 4.6, users using a SSO provider to login can be activated or deactivated with this endpoint. However, if their activation status in Mattermost does not reflect their status in the SSO provider, the next synchronization or login by that user will reset the activation status to that of their account in the SSO provider. Server versions 4.5 and before do not allow activation or deactivation of SSO users from this endpoint.
User can deactivate themselves.
User with manage_system
permission can activate or deactivate a user.
user_id required | string User GUID |
Use true
to set the user active, false
for inactive
active required | boolean |
User active status update successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "active": true
}
{- "status": "string"
}
Get a user's profile image based on user_id string parameter.
Must be logged in.
user_id required | string User GUID |
User's profile image
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "4xp9fdt77pncbef59f4k1qe83o" data, resp := Client.GetProfileImage(userID, "")
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
Set a user's profile image based on user_id string parameter.
Must be logged in as the user being updated or have the edit_other_users
permission.
user_id required | string User GUID |
image required | string <binary> The image to be uploaded |
Profile image set successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
import ( "io/ioutil" "log" "github.com/mattermost/mattermost-server/v5/model" ) Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") data, err := ioutil.ReadFile("profile_pic.png") if err != nil { log.Fatal(err) } userID := "4xp9fdt77pncbef59f4k1qe83o" ok, resp := Client.SetProfileImage(userID, data)
{- "status": "string"
}
Delete user's profile image and reset to default image based on user_id string parameter.
Must be logged in as the user being updated or have the edit_other_users
permission.
Minimum server version: 5.5
user_id required | string User GUID |
Profile image reset successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "4xp9fdt77pncbef59f4k1qe83o" // Deleting user's profile image consists on resetting it to default one ok, resp := Client.SetDefaultProfileImage(userID)
{- "status": "string"
}
Returns the default (generated) user profile image based on user_id string parameter.
Must be logged in. Minimum server version: 5.5
user_id required | string User GUID |
Default profile image
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "4xp9fdt77pncbef59f4k1qe83o" ok, resp := Client.SetDefaultProfileImage(userID)
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
Get a user object by providing a username. Sensitive information will be sanitized out.
Requires an active session but no other permissions.
username required | string Username |
User retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "4xp9fdt77pncbef59f4k1qe83o" user, resp := Client.GetUserByUsername(userID, "")
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
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.
No permissions required.
code required | string The recovery code |
new_password required | string The new password for the user |
User password update successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "code": "string",
- "new_password": "string"
}
{- "status": "string"
}
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.
Must be logged in as the user being updated or have the edit_other_users
permission.
user_id required | string User GUID |
activate required | boolean Use |
code | string The code produced by your MFA client. Required if |
User MFA update successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Feature is disabled
{- "activate": true,
- "code": "string"
}
{- "status": "string"
}
Generates an multi-factor authentication secret for a user and returns it as a string and as base64 encoded QR code image.
Must be logged in as the user or have the edit_other_users
permission.
user_id required | string User GUID |
MFA secret generation successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u" mfaSecret, resp = Client.GenerateMfaSecret(userID)
{- "secret": "string",
- "qr_code": "string"
}
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
Must be logged in as the user or have the demote_to_guest
permission.
user_id required | string User GUID |
User successfully demoted
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u" ok, resp = Client.demoteUserToGuest(userID)
{- "status": "string"
}
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
Must be logged in as the user or have the promote_guest
permission.
user_id required | string User GUID |
Guest successfully promoted
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u" ok, resp = Client.PromoteGuestToUser(userID)
{- "status": "string"
}
Convert a user into a bot.
Minimum server version: 5.26
Must have manage_system
permission.
user_id required | string User GUID |
User successfully converted
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") userId := "BbaYBYDV5IDOZFiJGBSzkw1k5u" bot, resp := Client.ConvertUserToBot(userId)
{- "status": "string"
}
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.
No permission required.
login_id required | string The email or username used to login |
MFA check successful
Invalid or missing parameters in URL or request body
{- "login_id": "string"
}
{- "mfa_required": true
}
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.
Must be logged in as the user the password is being changed for or have manage_system
permission.
user_id required | string User GUID |
current_password | string The current password for the user |
new_password required | string The new password for the user |
User password update successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "current_password": "string",
- "new_password": "string"
}
{- "status": "string"
}
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.
No permissions required.
email required | string The email of the user |
Email sent if account exists
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "email": "string"
}
{- "status": "string"
}
Get a user object by providing a user email. Sensitive information will be sanitized out.
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.
email required | string User Email |
User retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") email := "test@domain.com" user, resp := Client.GetUserByEmail(email, "")
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
Get a list of sessions by providing the user GUID. Sensitive information will be sanitized out.
Must be logged in as the user being updated or have the edit_other_users
permission.
user_id required | string User GUID |
User session retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "zWEyrTZ7GZ22aBSfoX60iWryTY" sessions, resp := Client.GetSessions(userID, "")
[- {
- "create_at": 0,
- "device_id": "string",
- "expires_at": 0,
- "id": "string",
- "is_oauth": true,
- "last_activity_at": 0,
- "props": { },
- "roles": "string",
- "team_members": [
- {
- "team_id": "string",
- "user_id": "string",
- "roles": "string",
- "delete_at": 0,
- "scheme_user": true,
- "scheme_admin": true,
- "explicit_roles": "string"
}
], - "token": "string",
- "user_id": "string"
}
]
Revokes a user session from the provided user id and session id strings.
Must be logged in as the user being updated or have the edit_other_users
permission.
user_id required | string User GUID |
session_id required | string The session GUID to revoke. |
User session revoked successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "session_id": "string"
}
{- "status": "string"
}
Revokes all user sessions from the provided user id and session id strings.
Must be logged in as the user being updated or have the edit_other_users
permission.
Minimum server version: 4.4
user_id required | string User GUID |
User sessions revoked successfully
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "zWEyrTZ7GZ22aBSfoX60iWryTY" ok, resp := Client.RevokeAllSessions(userID)
{- "status": "string"
}
Attach a mobile device id to the currently logged in session. This will enable push notifications for a user, if configured by the server.
Must be authenticated.
device_id required | string Mobile device id. For Android prefix the id with |
Device id attach successful
Invalid or missing parameters in URL or request body
No access token provided
{- "device_id": "string"
}
{- "status": "string"
}
Get a list of audit by providing the user GUID.
Must be logged in as the user or have the edit_other_users
permission.
user_id required | string User GUID |
User audits retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "zWEyrTZ7GZ22aBSfoX60iWryTY" audits, resp := Client.GetUserAudits(userID, 0, 100, "")
[- {
- "id": "string",
- "create_at": 0,
- "user_id": "string",
- "action": "string",
- "extra_info": "string",
- "ip_address": "string",
- "session_id": "string"
}
]
Verify the email used by a user without a token.
Minimum server version: 5.24
Must have manage_system
permission.
user_id required | string User GUID |
User email verification successful
Invalid or missing parameters in URL or request body
No access token provided
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u user, resp := Client.VerifyUserEmailWithoutToken(userID)
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "email": "string",
- "email_verified": true,
- "auth_service": "string",
- "roles": "string",
- "locale": "string",
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}, - "props": { },
- "last_password_update": 0,
- "last_picture_update": 0,
- "failed_attempts": 0,
- "mfa_active": true,
- "timezone": {
- "useAutomaticTimezone": true,
- "manualTimezone": "string",
- "automaticTimezone": "string"
}, - "terms_of_service_id": "string",
- "terms_of_service_create_at": 0
}
Verify the email used by a user to sign-up their account with.
No permissions required.
token required | string The token given to validate the email |
User email verification successful
Invalid or missing parameters in URL or request body
{- "token": "string"
}
{- "status": "string"
}
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.
No permissions required.
email required | string Email of a user |
Email send successful if email exists
Invalid or missing parameters in URL or request body
{- "email": "string"
}
{- "status": "string"
}
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.
No current authentication required except when switching from OAuth2/SAML to email.
current_service required | string The service the user currently uses to login |
new_service required | string The service the user will use to login |
string The email of the user | |
password | string The password used with the current service |
mfa_code | string The MFA code of the current service |
ldap_id | string The LDAP/AD id of the user |
Login method switch or request successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Feature is disabled
{- "current_service": "string",
- "new_service": "string",
- "email": "string",
- "password": "string",
- "mfa_code": "string",
- "ldap_id": "string"
}
{- "follow_link": "string"
}
Generate a user access token that can be used to authenticate with the Mattermost REST API.
Minimum server version: 4.1
Must have create_user_access_token
permission. For non-self requests, must also have the edit_other_users
permission.
user_id required | string User GUID |
description required | string A description of the token usage |
User access token creation successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "description": "string"
}
{- "id": "string",
- "token": "string",
- "user_id": "string",
- "description": "string"
}
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
Must have read_user_access_token
permission. For non-self requests, must also have the edit_other_users
permission.
user_id required | string User GUID |
page | integer Default: 0 The page to select. |
per_page | integer Default: 60 The number of tokens per page. |
User access tokens retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "adWv1qPZmHdtxk7Lmqh6RtxWxS" tokens, resp := Client.GetUserAccessTokensForUser(userID, 0, 100)
[- {
- "id": "string",
- "user_id": "string",
- "description": "string",
- "is_active": true
}
]
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
Must have manage_system
permission.
page | integer Default: 0 The page to select. |
per_page | integer Default: 60 The number of tokens per page. |
User access tokens retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") tokens, resp := Client.GetUserAccessTokens(0, 100)
[- {
- "id": "string",
- "user_id": "string",
- "description": "string",
- "is_active": true
}
]
Revoke a user access token and delete any sessions using the token.
Minimum server version: 4.1
Must have revoke_user_access_token
permission. For non-self requests, must also have the edit_other_users
permission.
token_id required | string The user access token GUID to revoke |
User access token revoke successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "token_id": "string"
}
{- "status": "string"
}
Get a user access token. Does not include the actual authentication token.
Minimum server version: 4.1
Must have read_user_access_token
permission. For non-self requests, must also have the edit_other_users
permission.
token_id required | string User access token GUID |
User access token retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") tokenID := "adWv1qPZmHdtxk7Lmqh6RtxWxS" token, resp := Client.GetUserAccessToken(tokenID)
{- "id": "string",
- "user_id": "string",
- "description": "string",
- "is_active": true
}
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
Must have revoke_user_access_token
permission. For non-self requests, must also have the edit_other_users
permission.
token_id required | string The personal access token GUID to disable |
Personal access token disable successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "token_id": "string"
}
{- "status": "string"
}
Re-enable a personal access token that has been disabled.
Minimum server version: 4.4
Must have create_user_access_token
permission. For non-self requests, must also have the edit_other_users
permission.
token_id required | string The personal access token GUID to enable |
Personal access token enable successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "token_id": "string"
}
{- "status": "string"
}
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
Must have manage_system
permission.
Search criteria
term required | string The search term to match against the token id, user id or username. |
Personal access token search successful
{- "term": "string"
}
[- {
- "id": "string",
- "user_id": "string",
- "description": "string",
- "is_active": true
}
]
Updates a user's authentication method. This can be used to change them to/from LDAP authentication for example.
Minimum server version: 4.6
Must have the edit_other_users
permission.
user_id required | string User GUID |
auth_data required | string Service-specific authentication data |
auth_service required | string The authentication service such as "email", "gitlab", or "ldap" |
User auth update successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Feature is disabled
{- "auth_data": "string",
- "auth_service": "string"
}
{- "auth_data": "string",
- "auth_service": "string"
}
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
Must be logged in as the user being acted on.
user_id required | string User GUID |
terms of service details
serviceTermsId required | string terms of service ID on which the user is acting on |
accepted required | string true or false, indicates whether the user accepted or rejected the terms of service. |
Terms of service action recorded successfully
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "serviceTermsId": "string",
- "accepted": "string"
}
{- "status": "string"
}
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
Must be logged in as the user being acted on.
user_id required | string User GUID |
User's accepted terms of service action
Invalid or missing parameters in URL or request body
No access token provided
User hasn't performed an action or the latest action was a rejection.
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") userID := "adWv1qPZmHdtxk7Lmqh6RtxWxS" userTermsOfService, resp := Client.GetUserTermsOfService(userID, "")
{- "user_id": "string",
- "terms_of_service_id": "string",
- "create_at": 0
}
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
Must have manage_system
permission.
Sessions successfully revoked.
No access token provided
Do not have appropriate permissions
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") response, err := Client.RevokeSessionsFromAllUsers()
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
Notify users in the given channel via websocket that the given user is typing. Minimum server version: 5.26
Must have manage_system
permission to publish for any user other than oneself.
user_id required | string User GUID |
channel_id required | string The id of the channel to which to direct the typing event. |
parent_id | string 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. |
User typing websocket event accepted for publishing.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "channel_id": "string",
- "parent_id": "string"
}
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
Gets all the upload sessions belonging to a user.
Minimum server version: 5.28
Must be logged in as the user who created the upload sessions.
user_id required | string The ID of the user. This can also be "me" which will point to the current user. |
User's uploads retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") uss, response := Client.GetUploadsForUser("fc6suoon9pbbpmhrb9c967paxe")
[- {
- "id": "string",
- "type": "attachment",
- "create_at": 0,
- "user_id": "string",
- "channel_id": "string",
- "filename": "string",
- "file_size": 0,
- "file_offset": 0
}
]
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
Must have manage_system
permission.
from required | string The current authentication type for the matched users. |
match_field required | string Foreign user field name to match. |
force required | boolean |
Successfully migrated authentication type to LDAP.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Feature is disabled
{- "from": "string",
- "match_field": "string",
- "force": true
}
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
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
Must have manage_system
permission.
from required | string The current authentication type for the matched users. |
matches required | object Users map. |
auto required | boolean |
Successfully migrated authentication type to LDAP.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Feature is disabled
{- "from": "string",
- "matches": { },
- "auto": true
}
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
Convert a bot into a user.
Minimum server version: 5.26
Must have manage_system
permission.
bot_user_id required | string Bot user ID |
set_system_admin | boolean Default: false Whether to give the user the system admin role. |
Data to be used in the user creation
string | |
username | string |
password | string |
first_name | string |
last_name | string |
nickname | string |
locale | string |
position | string |
props | object |
notify_props | object (UserNotifyProps) |
Bot successfully converted
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
{- "email": "string",
- "username": "string",
- "password": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "locale": "string",
- "position": "string",
- "props": { },
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}
}
{- "status": "string"
}
Convert a user into a bot.
Minimum server version: 5.26
Must have manage_system
permission.
user_id required | string User GUID |
User successfully converted
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") userId := "BbaYBYDV5IDOZFiJGBSzkw1k5u" bot, resp := Client.ConvertUserToBot(userId)
{- "status": "string"
}
Create a new bot account on the system. Username is required.
Must have create_bot
permission.
Minimum server version: 5.10
Bot to be created
username required | string |
display_name | string |
description | string |
Bot creation successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "username": "string",
- "display_name": "string",
- "description": "string"
}
{- "user_id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "display_name": "string",
- "description": "string",
- "owner_id": "string"
}
Get a page of a list of bots.
Must have read_bots
permission for bots you are managing, and read_others_bots
permission for bots others are managing.
Minimum server version: 5.10
page | integer Default: 0 The page to select. |
per_page | integer Default: 60 The number of users per page. There is a maximum limit of 200 users per page. |
include_deleted | boolean If deleted bots should be returned. |
only_orphaned | boolean When true, only orphaned bots will be returned. A bot is consitered orphaned if it's owner has been deactivated. |
Bot page retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
require 'vendor/autoload.php'; use \Gnello\Mattermost\Driver; $container = new \Pimple\Container([ "driver" => [ "url" => "https://your-mattermost-url.com", "login_id" => "email@domain.com", "password" => "Password1", ] ]); $driver = new Driver($container); $driver->authenticate(); $resp = $driver->getBotModel()->getBots([ "page" => 0, "per_page" => 60, "include_deleted" => true, "only_orphaned" => true, ]); if ($resp->getStatusCode() == 200) { $bots = json_decode($resp->getBody()); }
[- {
- "user_id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "display_name": "string",
- "description": "string",
- "owner_id": "string"
}
]
Partially update a bot 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.
Must have manage_bots
permission.
Minimum server version: 5.10
bot_user_id required | string Bot user ID |
Bot to be created
username required | string |
display_name | string |
description | string |
Bot patch successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "username": "string",
- "display_name": "string",
- "description": "string"
}
{- "user_id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "display_name": "string",
- "description": "string",
- "owner_id": "string"
}
Get a bot specified by its bot id.
Must have read_bots
permission for bots you are managing, and read_others_bots
permission for bots others are managing.
Minimum server version: 5.10
bot_user_id required | string Bot user ID |
include_deleted | boolean If deleted bots should be returned. |
Bot successfully retrieved.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
require 'vendor/autoload.php'; use \Gnello\Mattermost\Driver; $container = new \Pimple\Container([ "driver" => [ "url" => "https://your-mattermost-url.com", "login_id" => "email@domain.com", "password" => "Password1", ] ]); $driver = new Driver($container); $driver->authenticate(); $botUserID = "4xp9fdt77pncbef59f4k1qe83o"; $resp = $driver->getBotModel()->getBot($botUserID, [ "include_deleted" => true, ]); if ($resp->getStatusCode() == 200) { $bot = json_decode($resp->getBody()); }
{- "user_id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "display_name": "string",
- "description": "string",
- "owner_id": "string"
}
Disable a bot.
Must have manage_bots
permission.
Minimum server version: 5.10
bot_user_id required | string Bot user ID |
Bot successfully disabled.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
require 'vendor/autoload.php'; use \Gnello\Mattermost\Driver; $container = new \Pimple\Container([ "driver" => [ "url" => "https://your-mattermost-url.com", "login_id" => "email@domain.com", "password" => "Password1", ] ]); $driver = new Driver($container); $driver->authenticate(); $botUserID = "4xp9fdt77pncbef59f4k1qe83o"; $resp = $driver->getBotModel()->disableBot($botUserID); if ($resp->getStatusCode() == 200) { $disabledBot = json_decode($resp->getBody()); }
{- "user_id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "display_name": "string",
- "description": "string",
- "owner_id": "string"
}
Enable a bot.
Must have manage_bots
permission.
Minimum server version: 5.10
bot_user_id required | string Bot user ID |
Bot successfully enabled.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
require 'vendor/autoload.php'; use \Gnello\Mattermost\Driver; $container = new \Pimple\Container([ "driver" => [ "url" => "https://your-mattermost-url.com", "login_id" => "email@domain.com", "password" => "Password1", ] ]); $driver = new Driver($container); $driver->authenticate(); $botUserID = "4xp9fdt77pncbef59f4k1qe83o"; $resp = $driver->getBotModel()->enableBot($botUserID); if ($resp->getStatusCode() == 200) { $enabledBot = json_decode($resp->getBody()); }
{- "user_id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "display_name": "string",
- "description": "string",
- "owner_id": "string"
}
Assign a bot to a specified user.
Must have manage_bots
permission.
Minimum server version: 5.10
bot_user_id required | string Bot user ID |
user_id required | string The user ID to assign the bot to. |
Bot successfully assigned.
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
require 'vendor/autoload.php'; use \Gnello\Mattermost\Driver; $container = new \Pimple\Container([ "driver" => [ "url" => "https://your-mattermost-url.com", "login_id" => "email@domain.com", "password" => "Password1", ] ]); $driver = new Driver($container); $driver->authenticate(); $botUserID = "4xp9fdt77pncbef59f4k1qe83o"; $userID = "adWv1qPZmHdtxk7Lmqh6RtxWxS"; $resp = $driver->getBotModel()->assignBotToUser($botUserID, $userID); if ($resp->getStatusCode() == 200) { $assignedBot = json_decode($resp->getBody()); }
{- "user_id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "username": "string",
- "display_name": "string",
- "description": "string",
- "owner_id": "string"
}
Get a bot's LHS icon image based on bot_user_id string parameter.
Must be logged in. Minimum server version: 5.14
bot_user_id required | string Bot user ID |
Bot's LHS icon image
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Something went wrong with the server
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") botUserID := "4xp9fdt77pncbef59f4k1qe83o" data, resp := Client.GetBotIconImage(botUserID)
{- "status_code": 0,
- "id": "string",
- "message": "string",
- "request_id": "string"
}
Set a bot's LHS icon image based on bot_user_id string parameter. Icon image must be SVG format, all other formats are rejected.
Must have manage_bots
permission.
Minimum server version: 5.14
bot_user_id required | string Bot user ID |
image required | string <binary> SVG icon image to be uploaded |
SVG icon image set successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Content too large
Something went wrong with the server
Feature is disabled
import ( "io/ioutil" "log" "github.com/mattermost/mattermost-server/v5/model" ) Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") data, err := ioutil.ReadFile("icon_image.svg") if err != nil { log.Fatal(err) } botUserID := "4xp9fdt77pncbef59f4k1qe83o" ok, resp := Client.SetBotIconImage(botUserID, data)
{- "status": "string"
}
Delete bot's LHS icon image based on bot_user_id string parameter.
Must have manage_bots
permission.
Minimum server version: 5.14
bot_user_id required | string Bot user ID |
Icon image deletion successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
Something went wrong with the server
Feature is disabled
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Client.Login("email@domain.com", "Password1") botUserID := "4xp9fdt77pncbef59f4k1qe83o" ok, resp := Client.DeleteBotIconImage(botUserID)
{- "status": "string"
}
Convert a bot into a user.
Minimum server version: 5.26
Must have manage_system
permission.
bot_user_id required | string Bot user ID |
set_system_admin | boolean Default: false Whether to give the user the system admin role. |
Data to be used in the user creation
string | |
username | string |
password | string |
first_name | string |
last_name | string |
nickname | string |
locale | string |
position | string |
props | object |
notify_props | object (UserNotifyProps) |
Bot successfully converted
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
Resource not found
{- "email": "string",
- "username": "string",
- "password": "string",
- "first_name": "string",
- "last_name": "string",
- "nickname": "string",
- "locale": "string",
- "position": "string",
- "props": { },
- "notify_props": {
- "email": true,
- "push": "string",
- "desktop": "string",
- "desktop_sound": true,
- "mention_keys": "string",
- "channel": true,
- "first_name": true
}
}
{- "status": "string"
}
Create a new team on the system.
Must be authenticated and have the create_team
permission.
Team that is to be created
name required | string Unique handler for a team, will be present in the team URL |
display_name required | string Non-unique UI name for the team |
type required | string
|
Team creation successful
Invalid or missing parameters in URL or request body
No access token provided
Do not have appropriate permissions
{- "name": "string",
- "display_name": "string",
- "type": "string"
}
{- "id": "string",
- "create_at": 0,
- "update_at": 0,
- "delete_at": 0,
- "display_name": "string",
- "name": "string",
- "description": "string",
- "email": "string",
- "type": "string",
- "allowed_domains": "string",
- "invite_id": "string",
- "allow_open_invite": true
}
For regular users only returns open teams. Users with the "manage_system" permission will return teams regardless of type. The result is based on query string parameters - page and per_page.
Must be authenticated. "manage_system" permission is required to show all teams.
page | integer Default: 0 The page to select. |
per_page | integer Default: 60 The number of teams per page. |
include_total_count | boolean Default: false |
Team list retrieval successful
Invalid or missing parameters in URL or request body
No access token provided
import "github.com/mattermost/mattermost-server/v5/model" Client := model.NewAPIv4Client("https://your-mattermost-url.com") Clie