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:

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

Prefer a guided walkthrough with a test workspace? Follow Environment, then Step 1, Step 2, and Step 3.

Option 1: Log in with username and password

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:

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

Notes on the login endpoint:

• 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 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 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:

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 for a sample response.

Good practices

• Always authenticate over HTTPS to protect credentials.

• Rotate and expire tokens regularly; log out to invalidate a session token you no longer need.

• Sensitive operations may additionally require two-factor authentication headers (x-2fa-code, x-2fa-method).

Next steps

• Make your first call: Send Your First Message in 5 Minutes.

• Browse all login methods and token endpoints in the Authentication section.