Authentication

Rocket.Chat supports multiple authentication methods to secure API communication, including standard username-and-password login and OAuth integrations with providers such as Google.

To access protected Rocket.Chat API endpoints, you must include both a valid authentication token and your user ID in the request headers:

• x-Auth-Token : The authentication token that verifies your session.

• x-User-Id : The unique identifier of the authenticated user.

Authentication tokens

Authentication tokens uniquely identify an active user session within a Rocket.Chat workspace. They confirm the user’s identity and permissions, enabling secure access to API features and resources.

For any endpoint that requires authentication, include your token in the X-Auth-Token header.

Rocket.Chat supports two primary types of authentication tokens:

1. authToken : It is a temporary token issued after a successful login through any login endpoint. Workspace administrators can also generate an authToken on behalf of a user using the Create User Token endpoint.

2. Personal Access Token: It is a long-lived token that users can generate to securely access the API without exposing their primary credentials.

   • To create a token through the user interface, see the Manage Personal Access Tokens guide.

   • To generate one via the API, use the Get Personal Access Tokens endpoint.

The login response

Every login endpoint returns the same shape. A trimmed example from Login with Username and Password:

{
  "status": "success",
  "data": {
    "authToken": "9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq",
    "userId": "aobEdbYhXfu5hkeqG",
    "me": {
      "_id": "aYjNnig8BEAWeQzMh",
      "username": "rocket.cat",
      "name": "Rocket Cat",
      "roles": ["admin"]
    }
  }
}

Take data.authToken and data.userId from this response and pass them as the X-Auth-Token and X-User-Id headers.

Common workflows

Authenticate an integration

1. Log in with a dedicated integration account, or use a personal access token for long-lived access that survives logouts.

2. Pass the token and user ID as headers on every request.

3. Log out to invalidate the session token when you finish.

Call a 2FA-protected endpoint

1. Call the endpoint. If two-factor authentication is required, the API returns a totp-required error naming the required method in details.method.

2. Obtain the code for that method: your authenticator app for totp, the emailed code for email, or the user's hashed password for password.

3. Retry the request with the x-2fa-code and x-2fa-method headers. See the Two-Factor Authentication introduction for details.

Conventions

• Always call login endpoints over HTTPS to protect credentials.

• An authToken expires based on your workspace's token policy; a personal access token stays valid until it is regenerated or removed.

• A wrong or missing token returns HTTP 401 with "status": "error". A missing 2FA header returns a totp-required error.