Mattermost Getting Started: Quickstart Guide (2026)

Getting started overview

This guide provides a structured approach to initiating development and integration with Mattermost. It focuses on the fundamental steps required to get an environment set up, authenticate, and execute a basic API call. Mattermost offers two primary deployment models: Mattermost Cloud and self-hosted Mattermost Team Edition or Enterprise Edition deployment options. The choice of deployment affects initial setup, particularly regarding server access and URL configuration. Regardless of the deployment, interaction with the Mattermost platform is primarily facilitated through its REST API and WebSocket API Mattermost API reference.

The core of programmatic interaction with Mattermost involves authentication using Personal Access Tokens (PATs). These tokens grant applications specific permissions to interact with the Mattermost instance on behalf of a user. The process outlined here will guide you through creating such a token and using it to perform a simple action, such as retrieving user details, to confirm your setup is functional.

Below is a quick reference table summarizing the initial steps:

Create an account and get keys

To begin, you need access to a Mattermost instance. You have two primary options:

1. Mattermost Cloud: This is the quickest way to get started. Navigate to the Mattermost signup page and create a new workspace. You can choose the free tier, Mattermost Cloud Free, which offers core features for team collaboration. Once signed up, you will have a Mattermost workspace URL (e.g., https://your-workspace.mattermost.cloud).

2. Self-Hosted Mattermost Team Edition: For greater control and customization, you can install Mattermost Team Edition on your own server. This option requires a server (e.g., Ubuntu, Debian) and basic system administration knowledge. Detailed installation guides are available in the official Mattermost documentation for various operating systems.

Once you have access to a Mattermost instance, the next step is to generate a Personal Access Token (PAT). PATs are used to authenticate API requests and act as a secure, long-lived alternative to session tokens or traditional username/password authentication for programmatic access Mattermost Personal Access Token documentation. Follow these steps to generate a PAT:

1. Log in to your Mattermost instance (either Cloud or self-hosted).
2. Click on your profile picture in the top-left corner and select Profile.
3. Navigate to the Security tab.
4. Scroll down to Personal Access Tokens and click Create New Token.
5. Provide a descriptive name for your token (e.g., "API Integration").
6. The token will be displayed once. Copy this token immediately as it will not be shown again. Store it securely; treat it like a password.

This PAT will be included in the Authorization header of your API requests, prefixed with Bearer. For example, Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN.

Your first request

With your Mattermost instance accessible and a PAT generated, you can now make your first API request. This example demonstrates how to retrieve information about the currently authenticated user, which is a common "hello world" for API integrations. We will use curl for simplicity, but you can adapt this to any HTTP client or programming language (Go, JavaScript SDKs are available Mattermost SDKs).

First, set your Mattermost server URL and your PAT as environment variables for convenience and security:

export MATTERMOST_SERVER_URL="https://your-workspace.mattermost.cloud"
export MATTERMOST_PAT="YOUR_PERSONAL_ACCESS_TOKEN_HERE"

Replace https://your-workspace.mattermost.cloud with your actual Mattermost instance URL and YOUR_PERSONAL_ACCESS_TOKEN_HERE with the PAT you generated.

Now, execute the following curl command to fetch the current user's details:

curl -i -X GET \
  -H "Authorization: Bearer $MATTERMOST_PAT" \
  "$MATTERMOST_SERVER_URL/api/v4/users/me"

A successful response will return JSON object containing details about the user associated with the PAT, similar to this (truncated for brevity):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "user_id_string",
  "create_at": 1678886400000,
  "update_at": 1678886400000,
  "delete_at": 0,
  "username": "testuser",
  "email": "[email protected]",
  "nickname": "Test User",
  "first_name": "Test",
  "last_name": "User",
  "roles": "system_user",
  "locale": "en",
  "last_activity_at": 1678886400000,
  "status": "online",
  "timezone": {
    "automaticTimezone": "",
    "manualTimezone": "",
    "useAutomaticTimezone": true
  }
}

This 200 OK response confirms that your Mattermost instance is reachable, your PAT is valid, and you can successfully authenticate and interact with the API. For further details on the /users/me endpoint, consult the Mattermost API reference for user information.

Common next steps

After successfully making your first API call, you can explore various functionalities Mattermost offers for integration and automation:

1. Explore the API Reference: The Mattermost API documentation provides comprehensive details on all available endpoints, including those for managing channels, posts, users, and files. This is your primary resource for understanding what actions you can perform programmatically.

2. Create a Bot Account: For automated interactions, it's recommended to create a dedicated bot account instead of using a regular user's PAT. Bot accounts have specific permissions and can be managed separately Mattermost bot account creation guide.

3. Webhooks and Slash Commands: Integrate external services with Mattermost using incoming and outgoing webhooks, or create custom slash commands to trigger actions directly from Mattermost channels.

4. Mattermost Plugins: For more complex integrations or UI extensions, consider developing Mattermost plugins. Plugins allow you to extend the Mattermost server and web app functionality.

5. WebSocket API: For real-time event subscriptions, such as new messages or user status updates, utilize the Mattermost WebSocket API. This is crucial for building interactive bots or mirroring Mattermost activity.

6. Review Security Best Practices: Always adhere to security best practices when handling API keys and sensitive data. Consider using environment variables, secrets management tools, and limiting token scopes. For general API security principles, consult resources such as the OAuth 2.0 specification for broader context on token-based authentication.

Troubleshooting the first call

If your first API call does not return a 200 OK status, consider the following common issues and troubleshooting steps:

• 401 Unauthorized: This typically indicates an issue with your Personal Access Token (PAT). Double-check that:

  • The PAT is correctly copied and not truncated.
  • The Authorization header is correctly formatted as Bearer YOUR_PAT.
  • The PAT has not expired or been revoked. You can check and regenerate PATs in your Mattermost profile settings.
  • The user associated with the PAT has the necessary permissions for the requested action.

• 404 Not Found: This usually points to an incorrect Mattermost server URL or an invalid API endpoint path. Verify that:

  • MATTERMOST_SERVER_URL is set to the correct URL of your Mattermost instance (e.g., https://your-workspace.mattermost.cloud or http://localhost:8065 for a local install).
  • The API path (/api/v4/users/me) is correct as per the Mattermost API reference.
  • If self-hosting, ensure your Mattermost server is running and accessible from where you are making the request.

• CORS Issues (Cross-Origin Resource Sharing): If you are making requests from a web browser (e.g., via JavaScript in a web application), you might encounter CORS errors. Mattermost server administrators need to configure the AllowUntrustedInternalConnections and AllowCorsFrom settings in config.json to permit cross-origin requests from specific domains Mattermost configuration settings.

• Network Connectivity Issues: Ensure your machine has network access to the Mattermost server. If self-hosting, check firewall rules and network configurations.

• Server Logs: For self-hosted instances, review the Mattermost server logs (typically located in /opt/mattermost/logs/mattermost.log or similar) for detailed error messages that can provide clues about the problem.