User Management

Rocket.Chat provides a set of APIs to programmatically manage users, permissions, roles, and LDAP integration. These APIs allow administrators to automate user management tasks, enforce access control, and integrate with external identity providers.

The user object

Most endpoints in this category accept or return a user object. A trimmed example from Get User's Info:

{
  "user": {
    "_id": "5fRTXMt7DMJbpPJfh",
    "createdAt": "2023-07-10T16:44:58.548Z",
    "username": "test.john",
    "name": "Test John",
    "emails": [{ "address": "test.john@test.com", "verified": true }],
    "type": "user",
    "status": "offline",
    "active": true,
    "roles": ["user", "admin"],
    "lastLogin": "2023-10-10T23:40:46.093Z",
    "utcOffset": 1,
    "nickname": "tesuser2"
  },
  "success": true
}

Fields you use most often:

• _id: The unique user ID. Pass it as userId in requests, and as the X-User-Id header when the user authenticates.

• username and name: The unique handle and the display name. Most endpoints accept either userId or username.

• roles: The roles assigned to the user. For default roles, the role name and ID are the same.

• active: Whether the user can log in. Deactivated users keep their data but cannot sign in.

• type: user, bot, or app.

Users API

• Create, update, and delete user accounts via API requests.

• Manage user profiles programmatically, including names, emails, and avatars.

• Configure user preferences such as language settings and notification options.

• Generate and manage authentication tokens for API access and integrations.

Provision a user and grant access

1. Create the user with name, email, username, and password.

2. Assign a role to control what they can do.

3. Create a user token if an integration must act as this user.

Deactivate or remove a user

1. Set the user's active status to false to suspend access without deleting data.

2. Delete the user to remove them permanently. Set confirmRelinquish to also delete rooms where they are the last owner.

Authenticate an integration

1. Log in to receive authToken and userId, or generate a personal access token for long-lived access.

2. Pass these values as X-Auth-Token and X-User-Id headers on every request.

3. Log the user out to invalidate the session token.

Permissions API

• Define and enforce granular access controls for Rocket.Chat features.

• Assign or restrict permissions for actions like messaging, file uploads, and administrative tasks.

• Customize permission sets through API calls to align with security policies.

Roles API

• Assign predefined or custom roles (e.g., Administrator, Moderator, Guest) using API methods.

• Control role-based access to features and settings.

• Manage hierarchical roles to structure user permissions efficiently.

LDAP Integration API

• Programmatically configure and sync user accounts with an LDAP server.

• Perform test synchronizations to validate authentication and data consistency.

• Automate user provisioning and access management through directory service settings.

Sync users from a directory

1. Configure LDAP in your workspace settings.

2. Trigger LDAP Sync to import and update accounts based on your data sync settings.

Conventions

• Administrative endpoints require permissions such as create-user, edit-other-user-info, or view-full-other-user-info. Each endpoint page lists its required permissions.

• Sensitive operations, such as updating another user or syncing LDAP, require two-factor authentication headers (x-2fa-code, x-2fa-method).

• List endpoints such as Get Users List support count, offset, sort, and query query parameters.