---
title: "Authenticate a REST Client"
slug: "authenticate-a-rest-client"
updated: 2026-10-05T19:48:38Z
published: 2026-10-05T19:48:38Z
canonical: "developer.rocket.chat/authenticate-a-rest-client"
---

> ## 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.

# Authenticate a REST Client

This document condenses everything a REST client needs to authenticate with Rocket.Chat on a single page. Every authenticated request carries the same two headers:

```bash
X-Auth-Token: your-auth-token
X-User-Id: your-user-id
```

There are two ways to obtain these values: log in with a username and password (interactive use), or use a personal access token (scripts and integrations).

> [!NOTE]
> Prefer a guided walkthrough with a test workspace? Follow [Environment](/apidocs/environment), then [Step 1](/apidocs/step-1-register-yourself-as-a-user), [Step 2](/apidocs/step-2-authenticate-your-user), and [Step 3](/apidocs/step-3-retrieve-your-user-information).

## Option 1: Log in with username and password

```bash
curl -X POST https://<your-workspace-url>/api/v1/login \
     -H "Content-Type: application/json" \
     -d '{ "user": "your-username", "password": "your-password" }'
```

The response returns your credentials in `data.authToken` and `data.userId`:

```json
{
  "status": "success",
  "data": {
    "authToken": "9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq",
    "userId": "aobEdbYhXfu5hkeqG",
    "me": { ... }
  }
}
```

Notes on the [login endpoint](/apidocs/login-with-username-and-password):

- If your account has two-factor authentication enabled, pass your 2FA code in the `code` body parameter.
- To resume a session with a previously issued token instead of sending a password again, pass it in the `resume` body parameter.
- Other login methods (OAuth, LDAP, SAML) are listed in the [Authentication](/apidocs/authentication-api) section.

## Option 2: Use a personal access token

For scripts and integrations, use a personal access token instead of a password login. Tokens remain valid until revoked, so your client does not need to re-authenticate.

1. [Generate a personal access token](/apidocs/generate-personal-access-token) for your user.
2. Send the token as the `X-Auth-Token` header and your user ID as the `X-User-Id` header on every request, exactly like login-issued credentials.

## Verify your credentials

Call an authenticated endpoint to confirm the headers work. `/api/v1/me` returns your own account details:

```bash
curl https://<your-workspace-url>/api/v1/me \
     -H "X-Auth-Token: your-auth-token" \
     -H "X-User-Id: your-user-id"
```

A JSON response with `"success": true` and your profile confirms the client is authenticated. See [Step 3: Retrieve Your User Information](/apidocs/step-3-retrieve-your-user-information) for a sample response.

## Good practices

- Always authenticate over HTTPS to protect credentials.
- Rotate and expire tokens regularly; [log out](/apidocs/logout-user) to invalidate a session token you no longer need.
- Sensitive operations may additionally require [two-factor authentication headers](/apidocs/two-factor-authentication-api) (`x-2fa-code`, `x-2fa-method`).

## Next steps

- Make your first call: [Send Your First Message in 5 Minutes](/apidocs/send-your-first-message-in-5-minutes).
- Browse all login methods and token endpoints in the [Authentication](/apidocs/authentication-api) section.