Access your workspace¶

Available on Entry, Professional, Enterprise, and Enterprise Advanced plans

Access your Mattermost instance with your credentials using a web browser, the desktop app, or the mobile app for iOS or Android. Depending on how Mattermost is configured, you’ll log in using your email address, username, or single sign-on (SSO) username, and your password. See the Client availability documentation to learn which features are available on different Mattermost clients.

Tip

Can’t find your Mattermost link? Ask your company’s IT department or your Mattermost system admin for your organization’s Mattermost Site URL. It’ll look something like https://example.com/company/mattermost, mattermost.yourcompanydomain.com, or chat.yourcompanydomain.com. These URLs could also end in .net.

Web/Desktop

Web browser¶

Open a supported web browser.
Copy and paste the Mattermost server link into the browser’s address field.
Enter your user credentials to log into Mattermost.
Bookmark the Mattermost URL in your web browser of choice so logging into Mattermost is easy in the future.

Desktop app¶

Download and install the Mattermost desktop app from the App Store (macOS), Microsoft Store (Windows), or by using a package manager (Linux).
When prompted, enter the Mattermost server link and a display name for the Mattermost instance. The display name is helpful in cases where you connect to multiple Mattermost instances. See the server connections documentation for details.
Enter your user credentials to log into Mattermost.
If the server requires an authentication secret, you’ll be prompted to enter it when you connect. Enter the secret provided by your system admin and select OK. See the troubleshooting section below for help if you’re having issues.
The team that displays first in the team sidebar opens. If you’re not a member of a team yet, you’re prompted to select a team to join.

Note

When you log into Mattermost using external user credentials, such as Google or Entra ID, you’ll temporarily leave the desktop app during login while authenticating your credentials. Once you’re successfully logged in to Mattermost, you’ll be returned to the desktop app. See the Single Sign-On (SSO) section below for details on the external providers that Mattermosts supports.

Mobile

Download and install the Mattermost mobile app from the Apple App Store (iOS) or Google Play Store (Android).
When prompted, enter the Mattermost server link and a display name for the Mattermost instance. Server URLs must begin with either http:// or https://. The display name is helpful in cases where you connect to multiple Mattermost instances. See the server connections documentation for details.
Enter your user credentials to log into Mattermost.
Optionally toggle the Advanced Options section to enter an Authentication secret. This is an additional security measure that some organizations use. Your system admin can provide you with the secret if required. See the troubleshooting section below for help if you’re having issues.
The team that displays first in the team sidebar opens. If you’re not a member of a team yet, you’re prompted to select a team to join.

Reset your password¶

If you’ve forgotten your password, you can reset it on the login screen by selecting Forgot your password?, or by contacting your system admin for assistance.

Email address or username¶

When account creation with email is enabled by your system admin, you can log in with the username or email address used to create a Mattermost account.

Log in to Mattermost with your username or email address, or reset your password.

Single Sign-On (SSO)¶

When enabled by your system admin, you may log in using your GitLab, Google, Entra ID, AD/LDAP, or SAML credentials.

GitLab

When enabled by your system admin, you can log in with your GitLab account using a one-click login option.

Google

When enabled by your system admin, you can log in with your Google account using a one-click login option.

Entra ID

When enabled by your system admin, you can log in with your Entra ID account using a one-click login option.

AD/LDAP

When enabled by your system admin, you can log in with your AD/LDAP credentials. This lets you use the same username and password for Mattermost that you use for various other company services.

SAML

When enabled by your system admin, you can log in with your SAML credentials. This lets you use the same username and password for Mattermost that you use for various other company services.

Mattermost officially supports Okta, OneLogin, and Microsoft ADFS as an identity provider (IDP) for SAML, but you may use other SAML IDPs as well. See our SAML Single Sign-On documentation to learn more about configuring SAML for Mattermost.

Log in to Mattermost with SAML credentials, such as OneLogin.

Multi-factor authentication¶

If your system admin enables multi-factor authentication for your Mattermost instance, you can optionally set up multi-factor authentication for your Mattermost user account by selecting your profile picture located in the top-right corner of Mattermost, and going to Security > Multi-Factor Authentication.

If your system admin enforces multi-factor authentication, you are required to set up multi-factor authentication for your Mattermost account. When you attempt to log in to Mattermost, you’re directed to the multi-factor authentication setup page. You won’t be able to access Mattermost until multi-factor setup is complete. If you encounter issues setting up multi-factor authentication, contact your Mattermost system admin for assistance.

Troubleshooting authentication secrets¶

If you’re having trouble connecting to a Mattermost server that requires an authentication secret, consider the following troubleshooting tips:

Authentication secrets are case-sensitive: Ensure you’re entering the secret exactly as provided, including any uppercase letters, numbers, or special characters.
Spaces matter: Don’t add extra spaces before or after the secret.
Copy/paste issues: If copying the secret from a document, ensure you’re not accidentally copying extra characters. It may be safer to type it manually.
Contact your administrator: If you continue experiencing issues, contact your IT department or Mattermost system administrator. They can verify the secret is configured correctly on the server side.

Desktop

If you’re having trouble connecting to a server with an authentication secret:

Issue	What To Do
Error: Server authentication required	Your server requires an authentication secret. Enter the secret provided by your system administrator in the modal that appears.
Error: The provided authentication secret is incorrect	The secret you entered doesn’t match the server’s configuration. Verify with your system admin that you have the correct secret (secrets are case-sensitive).
Connection works but then stops	Your organization may have rotated the authentication secret. Try connecting again. The app will automatically prompt you to enter the new secret.
Modal doesn’t appear	If you’re not seeing the authentication prompt, try removing the server and adding it again. This will reset all stored credentials.

Mobile

If you’re having trouble connecting to a server with an authentication secret:

Issue	What To Do
Error: “Authentication secret is invalid”	Tap on the server entry, tap Edit, expand Advanced Options, verify the secret is entered correctly, and tap Save to retry.
Forgot to enter secret during setup	Tap on the server entry, tap Edit, expand Advanced Options, enter the secret in the Authentication secret field, and tap Save.
Need to update secret after rotation	Swipe left on the server, tap Edit, expand Advanced Options, update the Authentication secret field with the new value, and tap Save.
Error persists with correct secret	Try removing the server completely and adding it again with the authentication secret entered during initial setup.