---
title: "Authentication"
slug: "authentication-api"
status: "update"
updated: 2026-09-14T19:58:57Z
published: 2026-09-14T19:59:44Z
canonical: "developer.rocket.chat/authentication-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**](https://developer.rocket.chat/apidocs/create-users-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**](https://docs.rocket.chat/docs/manage-personal-access-tokens) guide.
  - To generate one via the API, use the [**Get Personal Access Tokens**](https://developer.rocket.chat/apidocs/generate-personal-access-token) endpoint.

## The login response

Every login endpoint returns the same shape. A trimmed example from [Login with Username and Password](/apidocs/login-with-username-and-password):

```json
{
  "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](/apidocs/login-with-username-and-password) with a dedicated integration account, or use a [personal access token](/apidocs/generate-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](/apidocs/logout) 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](/apidocs/introduction-to-two-factor-authentication) 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.