openapi: 3.0.0 info: version: 1.0.0 title: User Management # description: |- # User management in Rocket.Chat includes the following: # * **Users**: Manage [users](https://docs.rocket.chat/use-rocket.chat/workspace-administration/users), preferences, and tokens. # * **Permissions**: Manage user [permissions](https://docs.rocket.chat/use-rocket.chat/workspace-administration/permissions) and access. # * **Roles**: Assign and manage user [roles](https://docs.rocket.chat/use-rocket.chat/workspace-administration/permissions#roles). # * **LDAP**: Test and sync [LDAP](https://docs.rocket.chat/use-rocket.chat/authentication/ldap) connection. servers: - url: https://apiexplorer.support.rocket.chat paths: /api/v1/permissions.listAll: get: tags: - Permissions summary: List All Permissions description: |- Returns the list of permissions from the workspace. ### Changelog | Version | Description | | ---------------- | ------------| |0.73.0 | Added | operationId: get-permissions.listAll parameters: - name: updatedSince in: query description: |- Date as ISO string. If you include this parameter, the `update` and `remove` fields in the response will contain only those permissions updated and removed since this date and time. schema: type: string example: '2017-11-25T15:08:17.248Z' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' responses: '200': description: OK content: application/json: schema: type: object properties: update: type: array items: type: object properties: _id: type: string _updatedAt: type: string roles: type: array items: type: string remove: type: array items: type: object success: type: boolean examples: Success Example: value: update: - _id: access-permissions _updatedAt: '2018-11-28T11:55:49.106Z' roles: - admin - _id: add-oauth-service _updatedAt: '2018-11-28T12:59:51.974Z' roles: - admin - user remove: [] success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/permissions.update: post: summary: Update Permissions description: |- Update the permissions on the workspace. Permission required: `access-permissions` ### Changelog | Version | Description | | ---------------- | ------------| |0.66.0 | Added | operationId: post-api-v1-permissions.update requestBody: content: application/json: schema: type: object properties: permissions: type: array description: The array of roles to overwrite. items: type: object properties: _id: type: string description: Enter the permission ID. example: access-permissions roles: type: array items: type: string description: For default Rocket.Chat roles, you can enter the role names such as `admin`, `user`, `owner`, etc. If you are updating the permissions for a custom role, enter the custom role ID instead of the role name. Use the Get Roles endpoint to get the list of roles with IDs in your workspace. example: admin required: - permissions examples: Example 1: value: permissions: - _id: access-permissions roles: - admin responses: '200': description: OK content: application/json: schema: type: object properties: permissions: type: array items: type: object properties: _id: type: string roles: type: array items: type: string success: type: boolean examples: Success Example: value: permissions: - _id: access-permissions roles: - admin success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: Invalid body params errorType: error-invalid-body-params Example 2: value: success: false error: Editing permissions is not allowed errorType: error-edit-permissions-not-allowed '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' tags: - Permissions /api/v1/permissions.addRole: post: tags: - Permissions summary: Add Permission to a Role description: |- Grant a permission to a role. Permission required: `access-permissions`. To modify a setting-level permission, the `access-setting-permissions` permission is also required. ### Changelog | Version | Description | | ---------------- | ------------| |8.7.0 | Added | operationId: post-api-v1-permissions.addRole parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: permissionId: type: string description: The permission ID. example: create-team-channel role: type: string description: The role to grant the permission to. For default Rocket.Chat roles, enter the role name, such as `admin` or `user`. For custom roles, enter the role ID. example: user required: - permissionId - role examples: Example: value: permissionId: create-team-channel role: user responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string action: type: string examples: Invalid Parameters: value: success: false error: "must have required property 'role'" errorType: invalid-params Permission does not exist: value: success: false error: "Permission does not exist [error-invalid-permission]" errorType: error-invalid-permission details: method: authorization:addPermissionToRole action: Adding_permission Invalid Role: value: success: false error: "Role does not exist [error-invalid-role]" errorType: error-invalid-role details: method: authorization:addPermissionToRole action: Adding_permission '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: 'User does not have the permissions required for this action [error-unauthorized]' /api/v1/permissions.removeRole: post: tags: - Permissions summary: Remove Role from Permission description: |- Revoke a permission from a role. Permission required: `access-permissions`. To modify a setting-level permission, the `access-setting-permissions` permission is also required. ### Changelog | Version | Description | | ---------------- | ------------| |8.7.0 | Added | operationId: post-api-v1-permissions.removeRole parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: permissionId: type: string description: The permission ID. example: create-team-channel role: type: string description: The role to revoke the permission from. For default Rocket.Chat roles, enter the role name, such as `admin` or `user`. For custom roles, enter the role ID. example: user required: - permissionId - role examples: Example: value: permissionId: create-team-channel role: user responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: Invalid Parameters: value: success: false error: "must have required property 'role'" errorType: invalid-params Permission not found: value: success: false error: "Permission not found [error-permission-not-found]" errorType: error-permission-not-found details: method: authorization:removeRoleFromPermission '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: 'User does not have the permissions required for this action [error-unauthorized]' /api/v1/roles.create: post: tags: - Roles summary: Create Role description: |-

Create a new role in the workspace. See Custom Roles for further information. * You can't create new roles with the same name as existing roles. For example, it is not possible to create a new role with the name `admin`. * The scope can either be `Users`(user level) or `Subscriptions`(room level). * Permission required: `access-permissions` ### Changelog | Version | Description | | ---------------- | ------------| |6.0.0 | Moved to Enterprise plan. | |3.15.0 | The endpoint is no longer used to update roles. | |0.70.0 | Added | operationId: post-api-v1-roles.create requestBody: content: application/json: schema: type: object properties: name: type: string description: Enter the new role's name. example: newRole scope: type: string description: The new role's scope. The scope can either be Users (user level) or Subscriptions (room level). The default value is `Users`. example: Subscriptions description: type: string description: Enter a description for the new role. example: Role description mandatory2fa: type: boolean description: >- Whether the role should have a mandatory 2FA. The default value is `false`. If set to true, users assigned to this role are prompted to enter a 2FA code for certain activities. default: false required: - name examples: Example: value: name: Test Role scope: Users description: Testing Role for API mandatory2fa: false responses: '200': description: OK content: application/json: schema: type: object properties: role: type: object properties: _id: type: string name: type: string scope: type: string description: type: string protected: type: boolean mandatory2fa: type: boolean _updatedAt: type: string success: type: boolean examples: Success Example: value: role: _id: 646c431fa8c3a3ba32d0e1c4 name: support1 scope: Subscriptions description: Role support tier 1 protected: false mandatory2fa: false _updatedAt: '2023-05-23T04:37:51.161Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Missing Parameter: value: success: false errorType: invalid-params error: "must have required property 'name'" Role Already Exists: value: success: false error: >- Role name already exists [error-duplicate-role-names-not-allowed] errorType: error-duplicate-role-names-not-allowed Access Permission not Allowed: value: success: false error: >- Accessing permissions is not allowed [error-action-not-allowed] errorType: error-action-not-allowed '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' /api/v1/roles.update: post: tags: - Roles summary: Update Role description: |-

Update a role in the workspace. Permission required: `access-permissions` ### Changelog | Version | Description | | ---------------- | ------------| |6.0.0 | Moved to Enterprise plan. | operationId: post-api-v1-roles.update requestBody: content: application/json: schema: type: object properties: roleId: type: string example: 646c431fa8c3a3ba32d0e1c4 description: The role ID that you want to update. name: type: string example: newRole description: The updated name of the role. scope: type: string example: Subscriptions description: >- The updated scope of the role. The scope can either be Users (user level) or Subscriptions (room level). The default value is `Users`. description: type: string example: Role description description: Updated description for the role. mandatory2fa: type: boolean default: false description: >- Whether the role should have a mandatory 2FA. The default value is `false`. If set to true, users assigned to this role are prompted to enter a 2FA code for certain activities. required: - roleId - name examples: Example: value: roleId: 646c431fa8c3a3ba32d0e1c4 name: Test Role scope: Users description: Testing Role for API mandatory2fa: false responses: '200': description: OK content: application/json: schema: type: object properties: role: type: object properties: _id: type: string name: type: string scope: type: string description: type: string protected: type: boolean mandatory2fa: type: boolean _updatedAt: type: string success: type: boolean examples: Success Example: value: role: _id: 646c431fa8c3a3ba32d0e1c4 name: update role scope: Users description: Update Role support tier 1 protected: false mandatory2fa: false _updatedAt: '2023-05-23T05:33:33.730Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Missing Parameter: value: success: false errorType: invalid-params error: "must have required property 'name'" Access Permission not Allowed: value: success: false error: >- Accessing permissions is not allowed [error-action-not-allowed] errorType: error-action-not-allowed '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' /api/v1/roles.addUserToRole: post: tags: - Roles summary: Assign Role to User description: |- Assign a role to a user. Optionally, you can set this role to a user for a specific room. **Permissions required**: - `access-permissions`: Required to modify permissions for various roles - `assign-admin-role`: Permission to assign the admin role to other users ### Changelog | Version | Description | | ---------------- | ------------| |0.70.0 | Added | operationId: post-api-v1-roles.addUserToRole requestBody: description: |- By default, the three major room roles are available in Rocket.Chat are **Owner**, **Leader**, and **Moderator**. [Creating custom roles](https://docs.rocket.chat/use-rocket.chat/user-management/custom-roles) is exclusively available on the Enterprise plan. Refer to [Roles](https://docs.rocket.chat/setup-and-configure/roles-in-rocket.chat) for more information. content: application/json: schema: type: object properties: roleId: type: string example: 6579adcf2dd9f9d9514f6 description: The ID of an existing role. username: type: string description: The user name. example: test.fun roomId: type: string description: The ID of the room where the user should be assigned a role, if it is a room role. example: 4adb09baa5ad42 required: - roleName - username examples: Example: value: roleId: 6579adcf2dd9f9d9514f6 username: test.fun roomId: 64adb09baa5ad4273bfc responses: '200': description: OK content: application/json: schema: type: object properties: role: type: object properties: _id: type: string scope: type: string description: type: string mandatory2fa: type: boolean name: type: string protected: type: boolean _updatedAt: type: string success: type: boolean examples: Success Example: value: role: _id: auditor-log scope: Users description: '' mandatory2fa: false name: auditor-log protected: true _updatedAt: '2023-07-10T23:20:56.702Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: >- must have required property 'username' [error-invalid-role-properties] errorType: error-invalid-role-properties Example 2: value: success: false error: >- The required "userId" or "username" param provided does not match any users [error-invalid-user] errorType: error-invalid-user Example 3: value: success: false error: error-invalid-role-properties '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' /api/v1/roles.getUsersInRole: get: tags: - Roles summary: Get Users of a Role operationId: get-api-v1-roles.getUsersInRole parameters: - name: role in: query description: The ID of the role required: true schema: type: string example: 653ec9873c7460e18e6f - name: roomId in: query description: The room ID. schema: type: string example: hfiec783ifjl - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' responses: '200': description: OK content: application/json: schema: type: object properties: users: type: array items: type: object properties: _id: type: string username: type: string type: type: string status: type: string active: type: boolean name: type: string success: type: boolean examples: Success Example: value: users: - _id: voakrL3cHjYBwwRPq username: a type: user status: offline active: true name: a - _id: N2s7KG6YkzgJfXbyn username: b type: user status: offline active: true name: b success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'Query param "role" is required [error-param-not-provided]' errorType: error-param-not-provided Example 2: value: success: false error: '[error-invalid-roleId]' errorType: error-invalid-roleId '401': $ref: '#/components/responses/authorizationError' description: |- Gets the users that belong to a specific role. **Permissions required**: - `access-permissions`: Required to modify permissions for various roles - `view-other-user-channels`: Permission to view channels owned by other users. Required if the request includes a `roomId` ### Changelog | Version | Description | | ---------------- | ------------| |1.3.0 | Added | /api/v1/roles.list: get: tags: - Roles summary: Get Roles description: |- Gets all the roles in the workspace. ### Changelog | Version | Description | | ---------------- | ------------| |0.73.0 | Added `mandatory2fa` property | |0.70.0 | Added | operationId: get-api-v1-roles.list responses: '200': description: OK content: application/json: schema: type: object properties: roles: type: array items: type: object properties: _id: type: string description: type: string mandatory2fa: type: boolean protected: type: boolean scope: type: string name: type: string success: type: boolean examples: Success Example: value: roles: - _id: admin description: Admin mandatory2fa: false protected: true scope: Users - _id: moderator description: Moderator mandatory2fa: false protected: true scope: Subscriptions - _id: leader description: Leader mandatory2fa: false protected: true scope: Subscriptions - _id: owner description: Owner mandatory2fa: false protected: true scope: Subscriptions - _id: user description: '' mandatory2fa: false protected: true scope: Users - _id: bot description: '' mandatory2fa: false protected: true scope: Users - _id: guest description: '' mandatory2fa: false protected: true scope: Users - _id: anonymous description: '' mandatory2fa: false protected: true scope: Users - _id: livechat-agent name: livechat-agent scope: Users - _id: livechat-manager name: livechat-manager scope: Users - _id: livechat-guest name: livechat-guest scope: Users success: true '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' /api/v1/roles.sync: get: tags: - Roles summary: Get Updated Roles description: |- Gets all the roles in the workspace which are updated after a given date. ### Changelog | Version | Description | | ---------------- | ------------| |3.1.0 | Added | operationId: get-api-v1-roles.sync parameters: - name: updatedSince in: query description: Date as ISO string. required: true schema: type: string example: '2017-11-25T15:08:17.248Z' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' responses: '200': description: OK content: application/json: schema: type: object properties: roles: type: object properties: update: type: array items: type: object properties: _id: type: string description: type: string mandatory2fa: type: boolean protected: type: boolean scope: type: string remove: type: array items: type: object properties: _id: type: string description: type: string mandatory2fa: type: boolean protected: type: boolean scope: type: string success: type: boolean examples: Success Example: value: roles: update: - _id: admin description: Admin mandatory2fa: false protected: true scope: Users remove: - _id: user description: User mandatory2fa: false protected: true scope: Users success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: 'Match error: Missing key ''updatedSince''' '401': $ref: '#/components/responses/authorizationError' /api/v1/roles.delete: post: summary: Delete Role tags: - Roles responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: >- The role properties are invalid. [error-invalid-role-properties] errorType: error-invalid-role-properties Example 2: value: success: false error: >- Accessing permissions is not allowed [error-action-not-allowed] errorType: error-action-not-allowed '401': $ref: '#/components/responses/authorizationError' operationId: post-api-v1-roles.delete parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' description: |- Permission required: `access-permissions` - Roles that have the protected value as true can't be deleted (such as: `admin`, `moderator`, `user` and so on). - You cannot delete roles that are assigned to users. To do that, you must first remove this role from all the users. ### Changelog | Version | Description | | ---------------- | ------------| |3.17.0 | Added | requestBody: content: application/json: schema: type: object properties: roleId: type: string example: 6579adcf2dd9f9d9514f6 description: The ID of an existing role. required: - roleId parameters: [] /api/v1/roles.removeUserFromRole: post: summary: Remove Role from User tags: - Roles responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: >- The role properties are invalid. [error-invalid-role-properties] errorType: error-invalid-role-properties Example 2: value: success: false error: >- Accessing permissions is not allowed [error-action-not-allowed] errorType: error-action-not-allowed '401': $ref: '#/components/responses/authorizationError' operationId: post-api-v1-roles.removeUserFromRole parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' description: |- Remove a role from a user. Permission required: `access-permissions` requestBody: content: application/json: schema: type: object properties: roleId: type: string example: 6579adcf2dd9f9d9514f6 description: The ID of an existing role. username: type: string description: The username for which you want to remove the role. example: user08 scope: type: string description: 'Optionally, you can also provide the role scope. The options are `Users` and `Subscriptions`.' required: - roleId - username /api/v1/roles.getUsersInPublicRoles: get: summary: Get Users in Public Roles tags: - Roles responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: users: type: array items: type: object properties: _id: type: string username: type: string roles: type: array items: type: string success: type: boolean examples: Example 1: value: users: - _id: kb2WBkjkut4YJpFQk username: agent2 roles: - livechat-agent - _id: Ahgf5k9Ca4YEdMjwX username: test.agent roles: - admin - livechat-agent success: true '401': $ref: '#/components/responses/authorizationError' operationId: get-api-v1-roles.getUsersInPublicRoles description: |- Use this endpoint to get the list of roles other than `user`, such as admin, livechat, and custom roles. ### Changelog | Version | Description | | ---------------- | ------------| |7.10.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' /api/v1/users.create: post: tags: - Users summary: Create User description: |- Create a new user in your workspace. This endpoint is typically used by admins to create user accounts in the workspace. Permissions required: - `create-user`: Permission to create users - `edit-other-user-active-status`: Permission to enable or disable other accounts ### Changelog | Version | Description | | ---------------- | ------------| |0.48.0 | `role` property is now `roles` which is an array of strings for the roles to create the user with. | |0.45.0 | Users created via this now join the default channels. | |0.40.0 | Added | operationId: post-api-v1-users.create parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object required: - name - email - password - username properties: name: type: string description: The display name of the user. example: Test User email: type: string description: The email address for the user. example: email@user.tld1 password: type: string description: The password for the user. example: anypassyouwant username: type: string description: The username for the user. example: uniqueusername1 active: type: boolean description: 'Set the users'' active status. If the user is deactivated, they can not login. By default, the user is active.' example: true default: true nickname: type: string description: 'The nickname for the user. ' example: testusername bio: type: string description: The bio for the user. example: All about the user joinDefaultChannels: type: boolean description: 'Select whether users should automatically join default channels once they are created. By default, it is set to `true`.' example: true default: true statusText: type: string description: The status text of the user. example: On a vacation roles: type: array description: |- The roles to be assigned to this user. If it is not specified, the `user` role is assigned by default. **Note:** * For default roles, the role name and ID are the same. For custom roles, the name and ID are different. * If you are setting a custom role for a user, make sure to enter the custom role ID, and not the role name. Refer to [Roles](https://docs.rocket.chat/use-rocket.chat/workspace-administration/permissions#roles) for more information. items: type: string example: bot requirePasswordChange: type: boolean description: Should the user be required to change their password when they login? It is set to `false` by default example: false default: false setRandomPassword: type: boolean description: Should the user be assigned a random password once they are created? It is set to `false` by defualt. example: false default: false sendWelcomeEmail: type: boolean description: Should the user get a welcome email? It is set to `true` by default. example: false default: false verified: type: boolean description: Should the user's email address be verified when created? It is set to `false` by default. example: false default: false customFields: type: object example: clearance: High team: Queen description: |- A valid JSON object of key-value pairs consisting of additional fields to be added during user registration. By default, the value is `undefined`. To save custom fields, you must first define them in the [workspace admin settings](https://docs.rocket.chat/use-rocket.chat/workspace-administration/settings/accounts/custom-fields). For information on how to view the custom fields, see the [Get Users List](https://developer.rocket.chat/reference/api/rest-api/endpoints/user-management/users-endpoints/get-users-list) endpoint. responses: '200': description: OK content: application/json: schema: type: object properties: user: type: object properties: _id: type: string createdAt: type: string username: type: string emails: type: array items: type: object properties: address: type: string verified: type: boolean type: type: string roles: type: array items: type: string status: type: string active: type: boolean _updatedAt: type: string bio: type: string name: type: string nickname: type: string requirePasswordChange: type: boolean settings: type: object success: type: boolean examples: Success Example: value: user: _id: BsNr28znDkG8aeo7W createdAt: '2016-09-13T14:57:56.037Z' services: password: bcrypt: $2a$i7BFS55uFYRf5TE4ErSUH8HymMNAbpMAvsOcl2C username: uniqueusername emails: - address: email@user.tld verified: false type: user status: offline active: true roles: - user _updatedAt: '2016-09-13T14:57:56.175Z' name: name settings: {} success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string action: type: string examples: Permission Error: value: success: false error: 'Adding user is not allowed [error-action-not-allowed]' errorType: error-action-not-allowed details: method: insertOrUpdateUser action: Adding_user '401': $ref: '#/components/responses/authorizationError' /api/v1/users.register: post: tags: - Users summary: Register User description: |- * An external member can use this endpoint to create an account on the workspace. * The number of requests you can make and the interval between each request depends on the workspace's rate limiter settings. You can find the settings from **Manage** > **Workspace** > **Settings** > **Rate Limiter** > **API Rate Limiter**. ### Changelog | Version | Description | | ---------------- | ------------| |0.50.0 | Added | operationId: post-api-v1-users.register requestBody: content: application/json: schema: type: object properties: username: type: string description: The username for the user. example: rogersmith email: type: string description: The email for the user. example: roger@example.com pass: type: string description: The password for the user. example: passw0rd name: type: string description: |- The name of the user. The value can be an empty string if `Require Name For Signup` is disabled in [account registration](https://docs.rocket.chat/use-rocket.chat/workspace-administration/settings/accounts#registration). example: Roger Smith secretURL: type: string description: You may have been provided with a secret URL. It includes a string appended to the registration URL. For example, `https://workspacedomain.com/register/my-secret-code`. For this parameter, enter the additional string at the end of the URL. example: Jjwjg6gouWLXhMGKW required: - username - email - pass - name responses: '200': description: OK content: application/json: schema: type: object properties: user: type: object properties: _id: type: string type: type: string status: type: string active: type: boolean name: type: string utcOffset: type: integer username: type: string success: type: boolean examples: Success Example: value: user: _id: nSYqWzZ4GsKTX4dyK type: user status: offline active: true name: Example User utcOffset: 0 username: example success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''pass'' [invalid-params]' errorType: invalid-params parameters: [] /api/v1/users.update: post: tags: - Users summary: Update User Details description: |- Use this endpoint to update the details of an existing user. This endpoint requires 2FA. **Permissions required**: - `edit-other-user-password`: Permission to modify other user's passwords - `edit-other-user-info_description`: Permission to change other user's name, username or email address - `edit-other-user-active-status`: Permission to enable or disable other accounts ### Changelog | Version | Description | | ---------------- | ------------| |7.0.0 | Removed upsert behaviour and stopped allowing `joinDefaultChannels` param| |0.48.0 | Renamed to `users.update` | |0.35.0 | Added | operationId: post-api-v1-users.update parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - name: x-2fa-code in: header required: true description: >- Enter the 2FA code. This parameter is required if 2FA is enabled in your workspace. See the Introduction to Two-Factor Authentication document for details. schema: type: string example: '148750' - name: x-2fa-method in: header required: true schema: type: string description: 'Enter the method with which you get the 2FA code. It can be `email`, `totp`, or `password`. This parameter is required if 2FA is enabled in your workspace.' requestBody: content: application/json: schema: type: object properties: userId: type: string description: The user ID to update. This value must not be empty. example: PMGoujw82oETsaw9828rQh2oXM data: type: object description: 'The object that includes the user information to update with the following parameters. Note: If you provide an empty object, the user details are returned.' properties: name: type: string description: The name of the user. example: Agent 2 Updated email: type: string example: agent2@agent.com description: The email ID of the user. password: type: string example: passw0rd description: The password for the user. username: type: string example: example description: The username for the user. active: type: boolean description: >- Whether the user is active, which determines if they can log in. Setting this to `false` deactivates the user. If the user is the last owner of any room, or the only member of a private room, the request fails with `user-last-owner` unless `confirmRelinquish` is also `true`. See `confirmRelinquish`. default: true roles: type: array description: The roles the user has been assigned. items: type: string requirePasswordChange: type: boolean description: Whether the user should be required to change their password when they login. default: false sendWelcomeEmail: type: boolean default: false description: Whether the user should get a welcome email. freeSwitchExtension: type: string deprecated: true description: The voice call extension. In Rocket.Chat 9.0.0, this field will be renamed to `sipExtension`. verified: type: boolean description: Whether the user's email address should be verified. default: true customFields: type: object example: clearance: High team: Queen description: |- Any custom fields the user should have on their account. To save custom fields, you must first define the custom fields in the admin panel (Manage > Workspace > Settings > Accounts > Registration > Custom Fields). For details on how to configure this field, see [Custom Fields](https://docs.rocket.chat/use-rocket.chat/workspace-administration/settings/accounts/custom-fields). For information on how to view the custom fields, see the [Get Users List](https://developer.rocket.chat/reference/api/rest-api/endpoints/user-management/users-endpoints/get-users-list) endpoint. confirmRelinquish: type: boolean default: false description: >- Top-level body parameter (not inside `data`). Only used when `data.active` is `false`. Set to `true` to deactivate the user even if they are the last owner of a room, or the only member of a private room. If the room has other active members, the member who joined earliest becomes the new owner. If the user is the only member of a private room, or no other active member can take ownership, that room is deleted, together with every discussion that belongs to it. Public channels are not deleted. If omitted or `false` and the user is the last owner of any room, the request fails with `user-last-owner` and the user's active status is not changed. required: - userId - data responses: '200': description: OK content: application/json: schema: type: object properties: user: type: object properties: _id: type: string createdAt: type: string username: type: string emails: type: array items: type: object properties: address: type: string verified: type: boolean type: type: string roles: type: array items: type: string status: type: string active: type: boolean inactiveReason: type: string name: type: string _updatedAt: type: string __rooms: type: array items: type: string requirePasswordChange: type: boolean settings: type: object properties: {} statusText: type: string livechatStatusSystemModified: type: boolean statusLivechat: type: string success: type: boolean examples: Example: value: user: _id: PMGoujw82oETsaw9828rQh2oXM createdAt: '2026-02-24T23:22:54.986Z' username: agent2 emails: - address: agent2@agent.com verified: false type: user roles: - user - livechat-agent status: offline active: true inactiveReason: null name: Agent 2 Updated _updatedAt: '2026-02-25T14:25:59.157Z' __rooms: - GENERAL requirePasswordChange: false settings: {} statusText: '' livechatStatusSystemModified: false statusLivechat: not-available success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string action: type: string shouldBeRemoved: type: array items: type: string shouldChangeOwner: type: array items: type: string examples: Example 1: value: success: false error: 'Editing user is not allowed [error-action-not-allowed]' errorType: error-action-not-allowed details: method: insertOrUpdateUser action: Editing_user user-last-owner: value: success: false error: '[user-last-owner]' errorType: user-last-owner details: shouldBeRemoved: - cascade-test-group shouldChangeOwner: [] '401': $ref: '#/components/responses/authorizationError' /api/v1/users.updateOwnBasicInfo: post: tags: - Users summary: Update Own Basic Information description: |- Update your account information using this endpoint. * To change your email or password, you must confirm it using TOTP. If you don't have 2FA enabled in your account (token code or email), TOTP will require the current password method. Note that if 2FA is not enabled in the workspace, the 2FA headers are not required. * If you add the `currentPassword` encrypted in SHA256 to the request body, the request won't require TOTP again. ### Changelog | Version | Description | | ---------------- | ------------| |6.4.0 | Add `bio` and `statusType` parameters. | |0.62.2 | Added | operationId: post-api-v1-users.updateOwnBasicInfo parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/x-2fa-code' - $ref: '#/components/parameters/x-2fa-method' requestBody: content: application/json: schema: type: object x-examples: Example 1: data: email: test@test.com newPassword: testbb currentPassword: >- aa856615052ee58e557a2945d53bc90a228915e7d7687ea250f3b4b1581d6e53 nickname: baby girl bio: Auspicious baby username: roxie name: test test statusType: offline statusText: On a vacation customFields: {} properties: data: type: object description: >- An object of user data to be updated with the following parameters. If you enter an empty string, the user details are returned. properties: email: type: string example: example@example.com description: Email ID of the user. newPassword: type: string example: passw0rd description: The new password of the user. currentPassword: type: string description: The password for the user encrypted in SHA256. example: >- 5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5 nickname: type: string example: cake description: The nickname of the user. bio: type: string example: Engineer description: The bio of the user. username: type: string example: example description: The username of the user. name: type: string example: Example User description: Name of the user. statusType: type: string example: offline description: >- The status type of the user. It can be `online`, `busy`, `away`, or `offline`. statusText: type: string example: On a vacation description: The status text of the user. customFields: type: object description: Any custom fields the user should have on their account. You must define the custom fields in the workspace settings. required: - data responses: '200': description: OK content: application/json: schema: type: object properties: user: type: object properties: _id: type: string createdAt: type: string services: type: object properties: password: type: object properties: bcrypt: type: string email2fa: type: object properties: enabled: type: boolean changedAt: type: string resume: type: object properties: loginTokens: type: array items: type: object properties: when: type: string hashedToken: type: string twoFactorAuthorizedHash: type: string twoFactorAuthorizedUntil: type: string email: type: object properties: verificationTokens: type: array items: type: object properties: token: type: string address: type: string when: type: string totp: type: object properties: enabled: type: boolean passwordHistory: type: array items: type: string username: type: string emails: type: array items: type: object properties: address: type: string verified: type: boolean type: type: string status: type: string active: type: boolean _updatedAt: type: string __rooms: type: array items: type: string roles: type: array items: type: string name: type: string settings: type: object properties: preferences: type: object properties: themeAppearence: type: string profile: type: object properties: {} lastLogin: type: string statusConnection: type: string utcOffset: type: integer banners: type: object properties: versionUpdate-6_0_0: type: object properties: id: type: string priority: type: integer title: type: string text: type: string textArguments: type: array items: type: string link: type: string modifiers: type: array items: type: object properties: {} read: type: boolean versionUpdate-6_2_8: type: object properties: id: type: string priority: type: integer title: type: string text: type: string textArguments: type: array items: type: string link: type: string modifiers: type: array items: type: object properties: {} statusDefault: type: string statusText: type: string operator: type: boolean livechatStatusSystemModified: type: boolean statusLivechat: type: string livechatCount: type: integer livechat: type: object properties: maxNumberSimultaneousChat: type: string bio: type: string nickname: type: string success: type: boolean examples: Success Example: value: user: _id: rbAXPnMktTFbNpwtJ createdAt: '2023-02-20T13:42:07.119Z' services: password: bcrypt: >- $2b$10$E9ppW3T2itbMEcDvOdWBR.NXiW3YbifRHwBhjVkt26r1XS8yNhh6u email2fa: enabled: true changedAt: '2023-02-20T13:42:07.118Z' resume: loginTokens: - when: '2023-09-16T09:27:10.959Z' hashedToken: A1jmsVCHHH2SkXHrEJDfumN+VtUP3tcuJ/OGseGrRbA= twoFactorAuthorizedHash: 3067196228a830eacd6181a6977fe86a twoFactorAuthorizedUntil: '2023-09-19T16:40:58.767Z' - when: '2023-09-18T10:37:58.218Z' hashedToken: RLdxvu9dDnk6QRwFdaK3my1AoPeGaR5lTkK+zEhTuPk= - when: '2023-09-18T10:41:25.814Z' hashedToken: zWZ8wW9PNlVuI2Q65vK/9vytaONk1BXxaWcNld4qvEc= email: verificationTokens: - token: lHq_4L8Orgxu2p5NhfVb0V9kA7kO1VaBXA5GmaJiuX3 address: test@test.com when: '2023-05-23T18:47:07.142Z' totp: enabled: false passwordHistory: - >- $2b$10$n1.FV8S2mxz7GzXA392V5OaDa5X0WR1DQ4eGGFKI/wpdhS9sVIC6S - >- $2b$10$4I68O5mlR.C8dRhtZ4Mj6us6EMwRHNIUqEWQe/nOhISs4e8RtOliW - >- $2b$10$AU9Ncfd8bO5TpE.5iLMjyujdd6RVJaoeKckVqo3MMO9Ngc3oyMAs2 username: roxie emails: - address: test@test.com verified: true type: user status: offline active: true _updatedAt: '2023-09-19T16:10:58.873Z' __rooms: - GENERAL - siyr2oWQJBjQjhLwr - 6GFJ3tbmHiyHbahmC - 64f0f82c2c26843a68c1f7ba roles: - user - admin - livechat-agent - livechat-manager name: test test settings: preferences: themeAppearence: light profile: {} lastLogin: '2023-09-19T16:00:19.657Z' statusConnection: away utcOffset: 1 banners: versionUpdate-6_0_0: id: versionUpdate-6_0_0 priority: 10 title: Update_your_RocketChat text: New_version_available_(s) textArguments: - 6.0.0 link: >- https://github.com/RocketChat/Rocket.Chat/releases/tag/6.0.0 modifiers: [] read: true versionUpdate-6_2_8: id: versionUpdate-6_2_8 priority: 10 title: Update_your_RocketChat text: New_version_available_(s) textArguments: - 6.2.8 link: >- https://github.com/RocketChat/Rocket.Chat/releases/tag/6.2.8 modifiers: [] statusDefault: offline statusText: On a vacation operator: true livechatStatusSystemModified: false statusLivechat: available livechatCount: 8 livechat: maxNumberSimultaneousChat: '' bio: Engineer nickname: '' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''data'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/users.info: get: tags: - Users summary: Get User's Info description: |- Retrieves information about a user, limited to the details the caller is allowed to view. Look up the user by `userId`, `username`, `importId`, `email`, or `freeSwitchExtension`. Provide exactly one of these parameters per request. Starting in version 7.0.0, this endpoint no longer supports the `fields` parameter, even when the `ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS` environment variable is set to `true`. Use `includeUserRooms` instead. When the Premium **User status hiding** feature is enabled and the requested user has hidden their status from the caller, the response shows the user as `offline` and omits `statusText`, `statusSource`, `statusExpiresAt`, `statusDefault`, and `statusConnection`. This restriction also applies to administrators. Users always see their own status. In Rocket.Chat 9.0.0, the `freeSwitchExtension` parameter will be renamed to `sipExtension`. ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added status visibility filtering | |8.5.0 | Added `freeSwitchExtension` query parameter for user lookup | |8.4.0 | Added `email` query parameter for user lookup | |7.0.0 | Removed the `fields` query parameter | |3.4.0 | Added `unread` property inside `rooms` object | |0.70.0 | Added `rooms` property to response if the user request it and has the `view-other-user-channels` permission | |0.49.0 | Updated to support `userId` or `username` | |0.48.0 | Renamed to `users.info` | |0.35.0 | Added | operationId: get-api-v1-users.info parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: userId in: query description: 'The `userId` of the user. Alternatively, you can use `username`, `importId`, `email`, or `freeSwitchExtension` to retrieve user information.' required: false schema: type: string example: W7NHuX5ri2e3mu2Fc - schema: type: string in: query name: username description: 'The username of the user. Alternatively, you can use `userId`, `importId`, `email`, or `freeSwitchExtension` to retrieve user information.' - schema: type: string in: query name: importId description: 'The import ID of the user. Alternatively, you can use `userId`, `username`, `email`, or `freeSwitchExtension` to retrieve user information.' - schema: type: string in: query name: includeUserRooms description: Whether to include the list of rooms the user is a member of. - name: email in: query required: false description: Filter the results by entering the user's email. Alternatively, you can use `userId`, `username`, `importId`, or `freeSwitchExtension` to retrieve user information. schema: type: string example: john@example.com - name: freeSwitchExtension in: query required: false deprecated: true description: 'The FreeSwitch voice call extension assigned to the user. Alternatively, you can use `userId`, `username`, `importId`, or `email` to retrieve user information. In Rocket.Chat 9.0.0, this parameter will be renamed to `sipExtension`.' schema: type: string example: '1234' responses: '200': description: OK content: application/json: schema: type: object properties: user: type: object properties: _id: type: string createdAt: type: string username: type: string emails: type: array items: type: object properties: address: type: string verified: type: boolean type: type: string status: type: string active: type: boolean roles: type: array items: type: string name: type: string requirePasswordChange: type: boolean lastLogin: type: string statusConnection: type: string utcOffset: type: integer freeSwitchExtension: type: string deprecated: true description: The voice call extension. In Rocket.Chat 9.0.0, this field will be renamed to `sipExtension`. canViewAllInfo: type: boolean success: type: boolean examples: Success Example: value: user: _id: 5fRTXMt7DMJbpPJfh createdAt: '2023-07-10T16:44:58.548Z' services: password: true email2fa: enabled: true changedAt: '2023-07-10T16:44:58.546Z' resume: loginTokens: - when: '2023-10-05T18:55:02.996Z' hashedToken: ... - when: '2023-10-05T19:09:30.415Z' hashedToken: .... - when: '2023-10-10T23:40:46.098Z' hashedToken: .... username: test.john emails: - address: test.john@test.com verified: true type: user status: offline active: true roles: - user - admin name: Test John requirePasswordChange: false lastLogin: '2023-10-10T23:40:46.093Z' statusConnection: offline utcOffset: 1 statusText: '' avatarETag: GFoEi6wv3uAxnzDcD nickname: tesuser2 freeSwitchExtension: '1234' canViewAllInfo: true rooms: - _id: 651667dda2f73c7460e18cce unread: 1 rid: JKa7R9zu2DinBhBN9 name: Livestream t: c - _id: 64ac358a79f5c6e276cfe718 unread: 0 rid: GENERAL name: general t: c - _id: 64aca0e5aa5ad4273bfbfdb8 unread: 0 rid: 6GFJ3tbmHiyHbahmC name: test-audit t: c - _id: 64adb09baa5ad4273bfc0cc0 unread: 0 rid: 64adb09baa5ad4273bfc0cbf name: test-room t: c roles: - owner - _id: 64fd791c2c26843a68c1f7e5 unread: 0 rid: siyr2oWQJBjQjhLwr name: try t: c roles: [] - _id: g5xHGWAGLA7vZXwW8 rid: 5fRTXMt7DMJbpPJfhrbAXPnMktTFbNpwtJ name: roxie t: d unread: 2 - _id: 64ef8a982c26843a68c1f7ae unread: 0 rid: WDuJLFkjwk6L7LdFC name: new t: p roles: - leader success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Missing / invalid lookup: value: success: false error: |- must have required property 'userId' must have required property 'username' must have required property 'importId' must match a schema in anyOf [invalid-params] errorType: invalid-params User not found: value: success: false error: User not found. '401': $ref: '#/components/responses/authorizationError' /api/v1/users.list: get: tags: - Users summary: Get Users List description: |- Retrieves workspace users and the information the caller is allowed to view. Use `query` to locate a user and obtain their `userId` for the `users.info` endpoint. The `query` parameter is considered unsafe and is deprecated. Its support is expected to be removed in a future major version, and there is currently no direct replacement for email-based lookup. When the Premium **User status hiding** feature is enabled, users who have hidden their status from the caller appear as `offline`, and their detailed status fields are omitted. If `query` filters on a status field, those users are excluded from the filtered results. **Permissions required**: - `view-d-room`: View direct messages. - `view-full-other-user-info`: View complete user details, such as account creation and last login. - `view-outside-room`: View users outside the caller's rooms when `Apply_permission_view-outside-room` is enabled under **Settings** > **General** > **REST API**. ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added status visibility filtering | |8.4.0 | Added `email` query parameter for filtering | |0.49.0 | `Count` and `offset` query parameters supported. | |0.35.0 | Added | operationId: get-api-v1-users.list parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - schema: type: string in: query name: sort description: 'Sort the users in ascending (`1`) or descending (`-1`) order. The value must be entered as a JSON string. The options are as follows: * `status`: Sort by users'' status. For example, `sort={"status":1}` (this maps to the `active` status). * `createdAt`: Sort by the time of user creation. For example, `sort={"createdAt":-1}` * `name`: Sort by user name. For example, `sort={"name":1}`' - name: email in: query required: false description: |- Filter users by email address. Minimum length: 1 character. schema: type: string minLength: 1 nullable: true example: user@example.com responses: '200': description: OK content: application/json: schema: type: object properties: users: type: array items: type: object properties: _id: type: string username: type: string emails: type: array items: type: object properties: address: type: string verified: type: boolean type: type: string status: type: string active: type: boolean roles: type: array items: type: string name: type: string lastLogin: type: string nameInsensitive: type: string avatarETag: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success Example: value: users: - _id: DGsmi2J4WjizYn7jc username: uniqueusername emails: - address: email@user.tld verified: false type: user status: offline active: true roles: - bot - user name: name nameInsensitive: name - _id: uZ5JvvioeHK8Coyqe active: true type: user status: offline roles: - anonymous - user lastLogin: '2023-05-16T20:50:33.579Z' username: user-0 nameInsensitive: '' - _id: aspKK7FHe7iQgzexX active: true type: user status: offline roles: - anonymous - user lastLogin: '2023-05-12T10:44:46.703Z' username: user-00 name: User 00 emails: - address: user00@mail.cm verified: false nameInsensitive: user 00 count: 3 offset: 0 total: 3 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/users.setAvatar: post: summary: Set User Avatar operationId: post-api-v1-users.setAvatar responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: Missing Content-Type '401': $ref: '#/components/responses/authorizationError' description: |- Use this endpoint to change your or another user's avatar. You can change avatars only if the `AllowUserAvatarChange` setting under **Accounts** is enabled. To change another user's avatar, you need the permission: `edit-other-user-avatar`. ### Changelog | Version | Description | | ---------------- | ------------| |8.7.0 | Added optional `service` multipart field (stored as `avatarOrigin`) | |0.56.0 | Add support for `username` argument. | |0.48.0 | Set other users avatars if the callee has permission. | |0.46.0 | Added | parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: avatarUrl: type: string description: Enter the image URL you want to set as the user avatar. example: 'http://domain.tld/to/my/own/avatar.jpg' userId: type: string description: >- The ID or username of the user. If not provided, the avatar of the user who is sending the request is updated. Alternatively, you can enter the `username` parameter. required: - avatarUrl examples: Example: value: avatarUrl: 'http://domain.tld/to/my/own/avatar.jpg' multipart/form-data: schema: type: object properties: image: type: string format: binary description: The image file to upload as the new avatar. service: type: string description: >- Optional. The name of the OAuth/external service the avatar originates from (e.g. `google`, `facebook`, `gravatar`). Stored as `avatarOrigin`. example: 'google' userId: type: string description: >- The ID or username of the user. If not provided, the avatar of the user who is sending the request is updated. required: - image examples: Example: value: image: '@my-own-avatar.png' service: 'google' description: |- You have two options to set the user avatar: * Upload the image file to use as the new avatar, as form-data. For example, `image=@my-own-avatar.png`. Optionally include a `service` field to record which OAuth/external service the avatar came from (stored as `avatarOrigin`). * Enter the image URL you want to set as the user avatar in the request body, using the parameter `avatarUrl`. tags: - Users /api/v1/users.getAvatar: get: summary: Get User Avatar tags: - Users responses: '200': description: OK content: image/svg+xml: schema: type: string format: binary '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: >- The required "userId" or "username" param was not provided [error-user-param-not-provided] errorType: error-user-param-not-provided operationId: get-api-v1-users.getAvatar parameters: - schema: type: string example: BsNr28znDkG8aeo7W in: query name: userId description: 'The user ID. Alternatively, you can enter the `username` parameter.' required: true - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' description: |- View a user's avatar. ### Changelog | Version | Description | | ------------ | ------------| |0.50.0 | Added | /api/v1/users.resetAvatar: post: summary: Reset Avatar operationId: post-api-v1-users.resetAvatar responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: >- The required "userId" or "username" param was not provided [error-user-param-not-provided] errorType: error-user-param-not-provided Example 2: value: success: false error: 'Reset avatar is not allowed [error-not-allowed]' errorType: error-not-allowed details: method: users.resetAvatar '401': $ref: '#/components/responses/authorizationError' description: |- Reset a user's avatar to the default icon. By default, icons contain the user's initials. Permissions required, if the setting `AllowUserAvatarChange` is enabled: * `edit-other-user-avatar`: Permission to change other user's avatar * `manage-moderation-actions`: Permission to manage moderation actions, perform actions on reported users ### Changelog | Version | Description | | ---------------- | ------------| |0.55.0 | Added | parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: userId: type: string description: >- The user ID. Alternatively, you can enter the `username` parameter. example: BsNr28znDkG8aeo7W required: - userId examples: Example 1: value: userId: BsNr28znDkG8aeo7W tags: - Users /api/v1/users.setStatus: post: summary: Set User Status operationId: post-api-v1-users.setStatus responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing status or message parameter: value: success: false error: 'Match error: Failed Match.OneOf, Match.Maybe or Match.Optional validation' Invalid expiresAt date: value: success: false error: 'expiresAt must be a future date [error-invalid-date]' errorType: error-invalid-date '401': $ref: '#/components/responses/authorizationError' description: |- * You can set the status for yourself or another user. The `AllowUserStatusMessageChange` setting must be enabled in the `Accounts` workspace settings. * To change another user's status, you must have the `edit-other-user-info` permission. * According to your workspace settings (under **Accounts**), you will only be able to set the invisible or `offline` status if the `Allow Invisible status option` setting is enabled. ### Changelog | Version | Description | | ---------------- | ------------| |8.6.0 | Added `expiresAt` request parameter for timed status expiration. | |1.2.0 | Added | parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: message: type: string description: The user's status message. At least one of the `message` or `status` parameters is required. example: My status update status: type: string description: >- The user's status like `online`, `away`, `busy`, or `offline`. At least one of the `message` or `status` parameters is required. example: online expiresAt: type: string description: Date as an ISO 8601 string. Sets an expiration time for the status. When this time passes, the presence engine restores the user's previous status. Must be a future date. Omit this parameter to keep the status until it is changed again. example: '2026-06-22T18:00:00.000Z' userId: type: string example: zXuq7SvPKYbzYmfpo description: The user ID for which you want to set the status. You don't need to add this if you are setting the status for yourself. Alternatively, you can use the `username` parameter and enter the username for which you want to set the status. examples: Example 1: value: message: My status update status: online expiresAt: '2026-06-22T18:00:00.000Z' userId: zXuq7SvPKYbzYmfpo username: bob tags: - Users /api/v1/users.getStatus: get: tags: - Users summary: Get Status description: |- Gets a user's status in your workspace. ### Changelog | Version | Description | | ---------------- | ------------| |8.6.0 | Added `statusSource` and `statusExpiresAt` response fields. | |1.2.0 | Added | operationId: get-api-v1-users.getStatus parameters: - name: userId in: query description: >- The `userId` of the user. Alternatively, you can use the `username` property and value. If the value is not provided, the authenticated user is used. schema: type: string example: W7NHuX5ri2e3mu2Fc responses: '200': description: OK content: application/json: schema: type: object properties: _id: type: string description: The user ID. connectionStatus: type: string description: The connection status. Returned when requesting the authenticated user's own status. status: type: string statusSource: type: string description: The claim that set the current status. One of `internal`, `manual`, or `external`. Omitted when the user has no recorded status source. statusExpiresAt: type: string description: Date as an ISO 8601 string indicating when the current status expires. Omitted when the status has no expiration. success: type: boolean examples: Success Example: value: _id: W7NHuX5ri2e3mu2Fc connectionStatus: online status: online statusSource: manual statusExpiresAt: '2026-06-22T18:00:00.000Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/users.setActiveStatus: post: summary: Set User's Status Active operationId: post-api-v1-users.setActiveStatus responses: '200': description: '' content: application/json: schema: type: object properties: user: type: object properties: _id: type: string active: type: boolean success: type: boolean examples: Success Example: value: user: _id: jJNyu4BQFqdgEcqnR active: false success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: shouldBeRemoved: type: array items: type: string shouldChangeOwner: type: array items: type: string examples: Example 1: value: success: false error: |- must have required property 'activeStatus' [invalid-params] errorType: invalid-params user-last-owner: value: success: false error: '[user-last-owner]' errorType: user-last-owner details: shouldBeRemoved: - cascade-test-group shouldChangeOwner: [] '401': $ref: '#/components/responses/authorizationError' description: |- Activate or deactivate a user in the workspace. Any one of the following permissions is required: * `edit-other-user-active-status`: Change another user's active status. * `manage-moderation-actions`: Manage moderation actions on reported users. When a user is deactivated (`activeStatus=false`), Rocket.Chat revokes all of the user's login tokens and OAuth access tokens, refresh tokens, and authorization codes. The user can no longer call the REST API with previously issued OAuth credentials. ### Changelog | Version | Description | | ---------------- | ------------| |8.5.0 | Added OAuth access token, refresh token, and authorization code revocation on deactivation. | |3.7.0 | Added `confirmRelinquish` to the payload. | |0.75.0 | Added | parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object x-examples: Example 1: activeStatus: false userId: 5HmCfpoB7jp2uibTC properties: activeStatus: type: boolean description: The value of the active status. default: true userId: type: string description: The user ID whose status value is to be changed. example: 5HmCfpoB7jp2uibTC confirmRelinquish: type: boolean default: false description: >- Only used when `activeStatus` is `false`. Set to `true` to deactivate the user even if they are the last owner of a room, or the only member of a private room. If omitted or `false` and the user is the last owner of any room, the request fails with `user-last-owner`. required: - activeStatus - userId description: |- When deactivating a user (`activeStatus=false`) and `confirmRelinquish=true`: * If the user is the last owner of a room that has other active members, the member who joined earliest becomes the new owner. * If the user is the only member of a private room, or no other active member can take ownership, that room is deleted, together with every discussion that belongs to it, regardless of who is a member of those discussions. Public channels are not deleted. When `confirmRelinquish` is omitted or `false` and the user is the last owner of any room, or the only member of a private room, the request fails with `user-last-owner` and no change is made. `details.shouldBeRemoved` names the rooms that would be deleted. `details.shouldChangeOwner` names the rooms that would get a new owner. Child discussions that the user is not subscribed to are not listed; any room in `shouldBeRemoved` also takes its discussions with it. tags: - Users /api/v1/users.deactivateIdle: post: summary: Deactivate Idle Users operationId: post-api-v1-users.deactivateIdle responses: '200': description: '' content: application/json: schema: type: object properties: count: type: integer success: type: boolean examples: Success Example: value: count: 1 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''daysIdle'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: unauthorized description: |- Automatically deactivate idle users in your workspace based on the number of days and roles. For every user that this endpoint deactivates, Rocket.Chat clears the user's login tokens and revokes their OAuth access tokens, refresh tokens, and authorization codes. Deactivated users can no longer call the REST API with previously issued OAuth credentials. Permission required: `edit-other-user-active-status` ### Changelog | Version | Description | | ---------------- | ------------| |8.5.0 | Added login and OAuth token revocation for users deactivated by this endpoint. | |3.1.0 | Added | parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: daysIdle: type: integer description: The number of days that the user is idle. example: 2 role: type: string description: The user role. example: admin default: user required: - daysIdle examples: Example 1: value: daysIdle: 2 role: user tags: - Users /api/v1/users.getPresence: get: summary: Get Specific User's Presence operationId: get-api-v1-users.getPresence responses: '200': description: '' content: application/json: schema: type: object properties: presence: type: string success: type: boolean examples: Success Example: value: presence: offline success: true '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - schema: type: string example: BsNr28znDkG8aeo7W in: query name: userId description: >- The user ID. Alternatively, you can enter the `username` parameter. If not provided, the user who sending the request is retrieved. tags: - Users description: |- Get a user's presence in the workspace (offline, busy, active, or away). ### Changelog | Version | Description | | ---------------- | ------------| |0.49.0 | Updated to support `userId` or `username` | |0.48.0 | Renamed to `users.getPresence` | |0.35.0 | Added | /api/v1/users.presence: get: summary: Get Users Presence operationId: get-api-v1-users.presence responses: '200': description: '' content: application/json: schema: type: object properties: users: type: array items: type: object properties: _id: type: string name: type: string username: type: string status: type: string utcOffset: type: integer statusText: type: string description: The user's status message. statusSource: type: string description: 'The claim that set the user''s current status. One of `internal`, `manual`, or `external` (priority order: `internal` > `manual` > `external`). Omitted when the user has no recorded status source.' statusExpiresAt: type: string description: Date as an ISO 8601 string indicating when the user's current status expires. Omitted when the status has no expiration. avatarETag: type: string full: type: boolean success: type: boolean examples: Success Example: value: users: - _id: rocket.cat name: Rocket.Cat username: rocket.cat status: online utcOffset: 0 statusText: In a call statusSource: internal avatarETag: 5BB9B5ny5DkKdrwkq - _id: rocketchat.internal.admin.test name: RocketChat Internal Admin Test username: rocketchat.internal.admin.test status: online utcOffset: -2 statusText: Focus time statusSource: manual statusExpiresAt: '2026-06-22T18:00:00.000Z' avatarETag: iEbEm4bTT327NJjXt full: true success: true '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - schema: type: string example: '2019-05-22T12:11:45.392Z' in: query name: from description: >- The last date when the status was changed. Format: ISO 8601 datetime. Timezone, milliseconds and seconds are optional. If you don't pass `from` parameter, you'll get a list of all users' presence and the result will have a `full` field with value `true` . - schema: type: string example: J4sWseCgs8eEnWvhE,BsNr28znDkG8aeo7W in: query name: ids description: |- The IDs of the users whose presence you want. Provide one ID as `?ids=userId1`, multiple comma-separated IDs as `?ids=userId1,userId2`, or repeat the parameter as `?ids=userId1&ids=userId2`. description: |- Get presence of multiple workspace users. You can filter by date and user IDs. If the `Presence_broadcast_disabled` setting is true, the endpoint returns an empty array. You can find this setting under **Manage** > **Workspace** > **Settings** > **Troubleshoot**. When the Premium **User status hiding** feature is enabled, users who have hidden their status from the caller are omitted from the response. This applies to full results and requests filtered by `from` or `ids`. ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added status visibility filtering. | |8.6.0 | Added `statusSource` and `statusExpiresAt` to returned user objects. | |8.5.0 | Restored comma-separated `ids` query parameter support. | |1.1.0 | Added | tags: - Users /api/v1/users.delete: post: tags: - Users summary: Delete User description: |- Permanently deletes an existing user from your workspace. Permission required: `delete-user` ### Changelog | Version | Description | | ---------------- | ------------| |3.7.0 | Added `confirmRelinquish` to the payload. | |0.35.0 | Added | operationId: post-api-v1-users.delete parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - userId properties: userId: type: string example: BsNr28znDkG8aeo7W description: >- The `userId` of the user. Alternatively, you can use the `username` property and value. confirmRelinquish: type: boolean description: >- Deletes the user, even if they are the last owner of a room. By default, it is set to `false`. default: false examples: Example: value: userId: BsNr28znDkG8aeo7W confirmRelinquish: true responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean deletedRooms: description: "The rooms deleted as part of the user deletion process." type: array items: type: object examples: Example: value: success: true deletedRooms: [] '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example: value: success: false error: >- The required "userId" or "username" param was not provided [error-user-param-not-provided] errorType: error-user-param-not-provided '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: unauthorized /api/v1/users.deleteOwnAccount: post: tags: - Users summary: Delete Own Account description: |- Deletes your own user account. Requires the `Allow Users to Delete Own Account` setting enabled. Access this setting from **Manage** > **Workspace** > **Settings** > **Accounts**. ### Changelog | Version | Description | | ---------------- | ------------| |3.7.0 | Added `confirmRelinquish` to the payload. | |0.67.0 | Added | operationId: post-api-v1-users.deleteOwnAccount parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - password properties: password: type: string description: The password of user (encrypted in SHA256). example: 8f0e2f76e22b43e2855189877e7dc1e1e7d98c226c95db247cd1d547928334a9 confirmRelinquish: type: boolean description: >- Deletes own account even if user is the last owner of a room. default: false examples: Example 1: value: password: 8f0e2f76e22b43e2855189877e7dc1e1e7d98c226c95db247cd1d547928334a9 confirmRelinquish: false responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: Body parameter "password" is required. '401': $ref: '#/components/responses/authorizationError' /api/v1/users.createToken: post: tags: - Users summary: Create Users Token description: |- As a workspace admin, you can create temporary authentication tokens for users. This is the same type of session authentication token a user gets via login and expires the same way. * To use this endpoint, you must set a secret with the `CREATE_TOKENS_FOR_USERS_SECRET` environment variable in your deployment configuration. This secret will be used to authorize all requests made to this endpoint. * For SaaS workspaces, contact support to set this variable. * Permission required: `user-generate-access-token`. This permission is required only when you generate a token for another user; it is not required when you generate a token for your own account. * The maximum number of login tokens per user is 50. See this GitHub PR for details. ### Changelog | Version | Description | | ---------------- | ------------| |8.7.0 | Enforced the `user-generate-access-token` permission when generating a token for another user.| |8.0.0 | Added `CREATE_TOKENS_FOR_USERS_SECRET` environment variable to define a shared secret that will be used to authorize this endpoint.| |2.1.0 | Added ENV VAR to be able to use this endpoint (process.env.CREATE_TOKENS_FOR_USERS). | |0.56.0 | Added | operationId: post-api-v1-users.createToken parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: userId: type: string description: |- The ID of the user you want to generate a token for. example: BsNr28znDkG8aeo7W secret: type: string description: |- The secret defined in the `CREATE_TOKENS_FOR_USERS_SECRET` environment variable. Without the valid secret, you can't access this endpoint. example: pass123 required: - userId - secret examples: Create token for a user: value: userId: BsNr28znDkG8aeo7W secret: pass123 responses: '200': description: '' content: application/json: schema: type: object properties: data: type: object properties: userId: type: string authToken: type: string success: type: boolean examples: Token created: value: data: userId: BsNr28znDkG8aeo7W authToken: 2jdk99wuSjXPO201XlAks9sjDjAhSJmskAKW301mSuj9Sk success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid user: value: success: false error: >- The required "userId" or "username" param was not provided [error-user-param-not-provided] errorType: error-user-param-not-provided Invalid secret: value: success: false error: 'Not authorized [error-not-authorized]' errorType: error-not-authorized Missing permission: value: success: false error: 'Not authorized [error-not-authorized]' errorType: error-not-authorized '401': $ref: '#/components/responses/authorizationError' parameters: [] /api/v1/users.getPreferences: get: tags: - Users summary: Get User's Preferences description: Gets all the preferences of the authenticated user in the workspace. operationId: get-api-v1-users.getPreferences parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' responses: '200': description: OK content: application/json: schema: type: object properties: preferences: type: object properties: newRoomNotification: type: string newMessageNotification: type: string muteFocusedConversations: type: boolean useEmojis: type: boolean convertAsciiEmoji: type: boolean saveMobileBandwidth: type: boolean collapseMediaByDefault: type: boolean autoImageLoad: type: boolean emailNotificationMode: type: string roomsListExhibitionMode: type: string unreadAlert: type: boolean notificationsSoundVolume: type: integer desktopNotifications: type: string mobileNotifications: type: string enableAutoAway: type: boolean highlights: type: array items: type: object desktopNotificationDuration: type: integer viewMode: type: integer hideUsernames: type: boolean hideRoles: type: boolean hideAvatars: type: boolean hideFlexTab: type: boolean sendOnEnter: type: string roomCounterSidebar: type: boolean success: type: boolean examples: Success Example: value: preferences: newRoomNotification: door newMessageNotification: chime muteFocusedConversations: true useEmojis: true convertAsciiEmoji: true saveMobileBandwidth: true collapseMediaByDefault: false autoImageLoad: true emailNotificationMode: all roomsListExhibitionMode: category unreadAlert: true notificationsSoundVolume: 100 desktopNotifications: default mobileNotifications: default enableAutoAway: true highlights: [] desktopNotificationDuration: 0 viewMode: 0 hideUsernames: false hideRoles: false hideAvatars: false hideFlexTab: false sendOnEnter: normal roomCounterSidebar: false success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/users.setPreferences: post: summary: Set User Preferences operationId: post-api-v1-users.setPreferences responses: '200': description: OK content: application/json: schema: type: object properties: user: type: object properties: _id: type: string settings: type: object properties: preferences: type: object properties: enableAutoAway: type: boolean idleTimeLimit: type: integer desktopNotificationRequireInteraction: type: boolean desktopNotifications: type: string pushNotifications: type: string unreadAlert: type: boolean useEmojis: type: boolean convertAsciiEmoji: type: boolean autoImageLoad: type: boolean saveMobileBandwidth: type: boolean collapseMediaByDefault: type: boolean hideUsernames: type: boolean hideRoles: type: boolean hideFlexTab: type: boolean displayAvatars: type: boolean sidebarGroupByType: type: boolean sidebarCategories: type: array description: The sidebar categories saved for the user, including system groups and custom categories, in display order. items: type: object properties: _id: type: string name: type: string default: type: boolean showUnreads: type: boolean keepUnreadsOnTop: type: boolean sidebarViewMode: type: string sidebarDisplayAvatar: type: boolean sidebarShowUnread: type: boolean sidebarSortby: type: string statusVisibilityDenied: type: array description: The usernames of users who cannot see the authenticated user's presence and status message. Returned only to the authenticated user when the feature is enabled and the list is not empty. items: type: string showMessageInMainThread: type: boolean sidebarShowFavorites: type: boolean sendOnEnter: type: string messageViewMode: type: integer emailNotificationMode: type: string newRoomNotification: type: string newMessageNotification: type: string muteFocusedConversations: type: boolean notificationsSoundVolume: type: integer enableMessageParserEarlyAdoption: type: boolean mobileNotifications: type: string desktopNotificationDuration: type: integer dontAskAgainList: type: array items: type: object properties: {} highlights: type: array items: type: object properties: {} language: type: string success: type: boolean examples: Success Example: value: user: _id: rbAXPnMktTFbNpwtJ settings: preferences: statusVisibilityDenied: - bob - rocket.cat language: en success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid Parameter: value: success: false error: 'must have required property ''data'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' description: |- Set preferences for your account. If you want to edit another user's preferences, you need the permission `edit-other-user-info`. Use `statusVisibilityDenied` to specify the usernames of people who cannot see your presence and status message. Send an empty array to clear the list. Status hiding takes effect only when the Premium **User status hiding** setting (`Accounts_StatusVisibility_Enabled`) is enabled. You can change only your own list; if `userId` identifies another user, this preference is ignored. ### Changelog | Version | Description | | ---------------- | ------------| |8.9.0 | Added the `sidebarCategories` preference. | |8.8.0 | Added the `statusVisibilityDenied` preference. | |8.6.0 | Added `utcOffset` property. | |2.3.0 | Added `desktopNotificationRequireInteraction` property. | parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object required: - data properties: userId: type: string description: 'The user ID whose preferences you want to change. If an ID is not provided, the preferences will be set for the user who is sending the request.' data: type: object description: The object with the following preference details. properties: language: type: string description: The preferred language for the user. example: en newRoomNotification: type: string example: chime description: Set the sound for new room notifications. The notification sounds are customizable, you can check the preferences in your workspace account for the list of options available. default: door newMessageNotification: type: string example: chime description: New message notification sound. The notification sounds are customizable, you can check the preferences in your workspace account for the list of options available. default: chime muteFocusedConversations: type: boolean description: 'When set to true, open and active rooms will not create notification sounds.' clockMode: type: integer description: |- The valid display formats for the clock. You can enter the values 0, 1, or 2. * `0`: System default * `1`: 12-hour clock * `2`: 24-hour clock useEmojis: type: boolean description: A boolean value that indicates whether the user has enabled the option to use emojis. convertAsciiEmoji: type: boolean description: A boolean value that indicates whether the user has enabled the option to convert ASCII emojis. saveMobileBandwidth: type: boolean description: A boolean value that indicates whether the user has enabled the option to save mobile bandwidth. collapseMediaByDefault: type: boolean description: A boolean value that indicates whether the user has enabled the option to collapse media by default. autoImageLoad: type: boolean description: A boolean value indicates whether the user has enabled the option to load images automatically. emailNotificationMode: type: string example: mentions description: |- The preferred mode for email notifications. The options are: * `all`: Get desktop notifications for all messages. * `mentions`: Get the notifications only for mentions. * `nothing`: Get no desktop notifications. unreadAlert: type: boolean description: A boolean value indicates whether the user has enabled the option. notificationsSoundVolume: type: integer description: The sound volume for notifications. desktopNotifications: type: string description: |- The type of desktop notifications. * `all`: Get desktop notifications for all messages. * `mentions`: Get the notifications only for mentions. * `nothing`: Get no desktop notifications. example: mentions pushNotifications: type: string example: mentions description: |- The type of push notifications. * `all`: Get push notifications for all messages. * `mentions`: Get the notifications only for mentions. * `nothing`: Get no push notifications. enableAutoAway: type: boolean description: A boolean value that indicates whether the user has enabled the option to update the status as away after a certain amount of idle time. highlights: type: array description: The message highlights section. You will be notified when someone mentions a word or phrase that you add here. Highlight words are not case-sensitive. items: type: string example: '["deploy", "docker"]' messageViewMode: type: integer description: |- The preferred view mode for the messages i. The available options are: * `0` - Normal * `1` - Cozy * `2` - Compact hideUsernames: type: boolean description: A boolean value that indicates whether the user has enabled the option to hide usernames. hideRoles: type: boolean description: A boolean value that indicates whether the user has enabled the option to hide roles. displayAvatars: type: boolean description: A boolean value that indicates whether the user has enabled the option to display user avatars. hideFlexTab: type: boolean description: A boolean value that indicates whether the user has enabled the option to automatically close the right sidebar in rooms when you click outside them. sendOnEnter: type: string description: |- Set how you want the **Enter** key to behave when sending messages. * `normal` - Send messages with the **Enter** key. * `alternative` - Send messages with **Enter** + **Ctrl/Alt/Shift/Cmd**. * `desktop` - Send messages with **Enter** only on the desktop. idleTimeLimit: type: integer description: 'The time limit that is to be considered as idle time. After this time, the user status changes to `away`.' example: 300 sidebarShowFavorites: type: boolean description: A boolean value that indicates whether the user has enabled the option to show favorites on the sidebar. sidebarShowUnread: type: boolean description: A boolean value that indicates whether the user has enabled the option to show unread messages in the sidebar. statusVisibilityDenied: type: array description: The usernames of users who cannot see your presence and status message. Send an empty array to clear the list. items: type: string sidebarSortby: type: string description: |- To sort the messages in the sidebar alphabetically or by activity. The values can be: * `activity` * `alphabetical` sidebarViewMode: type: string description: |- The view mode of the sidebar. The values can be: * `extended` * `medium` * `condensed` sidebarDisplayAvatar: type: boolean description: A boolean value that indicates whether the user has enabled the option to display avatars in the sidebar. sidebarGroupByType: type: boolean description: A boolean value that indicates whether the user has enabled the option to show the grouped values in the sidebar. sidebarCategories: type: array description: |- The full, ordered list of sidebar categories for the user. The array replaces the stored list, so include every category you want to keep. Each entry is either a system group (such as `Favorites` or `Channels`) marked with `default: true`, or a custom category created by the user. Custom category names are trimmed and must contain 1 to 30 characters, and `_id` values must be unique in the array. Otherwise, the request fails with `error-invalid-param`. Custom categories are available in Commercial, Government, and Defense plans. items: type: object required: - _id - name additionalProperties: false properties: _id: type: string description: The category ID. For system groups, this is the group key, for example `Favorites`, `Channels`, `Direct_Messages`, `Discussions`, or `Teams`. name: type: string minLength: 1 maxLength: 30 description: The category name. default: type: boolean description: Whether the entry is a system group rather than a custom category. showUnreads: type: boolean description: Whether to show unread rooms in the category. keepUnreadsOnTop: type: boolean description: Whether to keep unread rooms at the top of the category. example: - _id: Favorites name: Favorites default: true - _id: qT7bXk2mZ9wLpR4sD name: Project Apollo showUnreads: true keepUnreadsOnTop: false - _id: Channels name: Channels default: true dontAskAgainList: type: array description: |- This field stores all the "warnings" a user opted not to be displayed again. An example where this works is when hiding a room. "dontAskAgainList\":[{\"action\":\"hideRoom\",\"label\":\"Hide\"}]" items: type: object properties: action: type: string label: type: string notifyCalendarEvents: type: boolean description: 'If you are using Outlook Calendar in your workspace, you can enable or disable calendar event notifications using this parameter.' default: false themeAppearence: type: string example: light default: auto description: "Set your preferrred workspace theme. The options are:\r\n* `light`\r\n* `dark`\r\n* `auto`\r\n* `high-contrast`" masterVolume: type: number description: Control the volume for all sounds coming from your workspace. alsoSendThreadToChannel: type: string description: "When replying to a thread, select how your replies should be sent to the room:\r\n* `never`: Thread replies are not sent to the channel.\r\n* `always`: Thread replies are sent to the channel.\r\n* `default`: Defaults to the workspace settings set by the admin." desktopNotificationRequireInteraction: type: boolean description: 'When set to true, notifications will remain in the notification panel until they are visited or closed.' showThreadsInMainChannel: type: boolean description: 'When set to true, all replies under a thread will also be displayed directly in the main room. When disabled, they''re displayed based on the sender''s choice.' fontSize: type: string description: "Set the font size. The options are:\r\n* `small`\r\n* `medium`\r\n* `large`" receiveLoginDetectionEmail: type: boolean description: Set this option to true to get an email notification whenever a login is made to your account. omnichannelTranscriptPDF: type: boolean description: Set to true to always export the transcript as PDF at the end of Omnichannel conversations. omnichannelTranscriptEmail: type: boolean description: Set to true to always send the transcript to contacts at the end of conversations. omnichannelHideConversationAfterClosing: type: boolean description: Set to true to redirect agents to the home page after closing a conversation. enableMobileRinging: type: boolean description: 'If you are using the Rocket.Chat Voice feature, you can set this parameter to true for mobile call notifications.' utcOffset: type: number description: The user's UTC offset in hours. Used to localize times such as notification schedules. example: -3 examples: Example: value: userId: rbAXPnMktTFbNpwtJ data: language: en newRoomNotification: door newMessageNotification: chime muteFocusedConversations: true clockMode: 0 useEmojis: true convertAsciiEmoji: true saveMobileBandwidth: true collapseMediaByDefault: true autoImageLoad: true emailNotificationMode: mentions unreadAlert: true notificationsSoundVolume: 0 desktopNotifications: mentions pushNotifications: mentions enableAutoAway: true highlights: - '["deploy", "docker"]' messageViewMode: 0 hideUsernames: true hideRoles: true displayAvatars: true hideFlexTab: true sendOnEnter: string idleTimeLimit: 300 sidebarShowFavorites: true sidebarShowUnread: true statusVisibilityDenied: - bob - rocket.cat sidebarSortby: string sidebarViewMode: string sidebarDisplayAvatar: true sidebarGroupByType: true sidebarCategories: - _id: Favorites name: Favorites default: true - _id: qT7bXk2mZ9wLpR4sD name: Project Apollo showUnreads: true keepUnreadsOnTop: false - _id: Channels name: Channels default: true dontAskAgainList: - {} notifyCalendarEvents: false themeAppearence: auto tags: - Users /api/v1/users.forgotPassword: parameters: [] post: summary: Forgot Password operationId: post-api-v1-users.forgotPassword responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string examples: Success Example: value: status: success '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: The 'email' param is required description: |- Send an email to reset your password. Ensure that you have completed the configuration of the email; otherwise, your users will not receive the mail normally. Access this from **Manage** > **Workspace** > **Settings** > **Email**. To use this endpoint, the `PasswordReset` setting must be enabled in **Settings** > **Accounts** > **Registration** > **Password Reset**. ### Changelog | Version | Description | | ---------------- | ------------| |0.64.0 | Added | parameters: [] requestBody: content: application/json: schema: type: object properties: email: type: string description: The email to send password reset link. example: email@rocket.cat required: - email examples: Example 1: value: email: email@rocket.cat tags: - Users /api/v1/users.getUsernameSuggestion: get: tags: - Users summary: Get Username Suggestion description: |- Get a username suggestion for the authenticated user. ### Changelog | Version | Description | | ---------------- | ------------| |0.65.0 | Added | operationId: get-api-v1-users.getUsernameSuggestion parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' responses: '200': description: OK content: application/json: schema: type: object properties: result: type: string success: type: boolean examples: Example 1: value: result: rocket.mic success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/users.getAvatarSuggestion: get: summary: Get Avatar Suggestion tags: - Users responses: '200': description: OK content: application/json: schema: type: object properties: suggestions: type: object properties: gravatar: type: object properties: service: type: string url: type: string blob: type: string contentType: type: string success: type: boolean examples: Example 1: value: suggestions: gravatar: service: gravatar url: 'https://s.gravatar.com/avatar/6da0187ff0de738a86a62b0e9e34ffbf?default=404&size=200' blob: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAgAElEQVR42my9y49k2ZHm9zM75153j8jIjMysyqxKVrGKZJNsstjvbrTUg1bPQAIaGgkYCCMtpIWglTba6g+YP0CA/gBBO61moYUEYQRpMNBooWlyptmcLrJZZFXWu/L9iqe733uOmRZ27nWP4hSQiKjMCPfr955j9tn3fWZHfvCX/8iTLhA6/vCHP+TenWOuHR5Rxy0' contentType: image/png success: true '401': $ref: '#/components/responses/authorizationError' operationId: get-api-v1-users.getAvatarSuggestion description: |- Use this endpoint to get suggestions for your workspace avatar image. The endpoint may return an empty string if no images associated with your email ID are found. Gravatar suggestions are deprecated since Rocket.Chat 8.9.0 and will be removed in Rocket.Chat 9.0.0. After that, the response will only include avatars from OAuth services. parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' /api/v1/users.checkUsernameAvailability: get: tags: - Users summary: Check Username Availability description: 'Check if the username is available or used by another user' operationId: get-api-v1-users.checkUsernameAvailability parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: username in: query required: true description: 'The username to check for availability' schema: type: string example: johnDoe responses: '200': description: OK content: application/json: schema: type: object properties: result: type: boolean success: type: boolean examples: Example 1: value: result: true success: true Example 2: value: result: false success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string field: type: string examples: Example 1: value: success: false error: 'must have required property ''username'' [invalid-params]' errorType: invalid-params Example 2: value: success: false error: 'system is blocked and can''t be used! [error-blocked-username]' errorType: error-blocked-username details: method: "checkUsernameAvailability" field: "system" '401': $ref: '#/components/responses/authorizationError' /api/v1/users.generatePersonalAccessToken: parameters: [] post: summary: Generate Personal Access Token operationId: post-api-v1-users.generatePersonalAccessToken responses: '200': description: OK content: application/json: schema: type: object properties: token: type: string success: type: boolean examples: Success Example: value: token: 2jdk99wuSjXPO201XlAks9sjDjAhSJmskAKW301mSuj9Sk success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string codeGenerated: type: boolean availableMethods: type: array items: type: object properties: {} examples: Example 1: value: success: false error: 'TOTP Required [totp-required]' errorType: totp-required details: method: password codeGenerated: false availableMethods: [] Example 2: value: success: false error: The 'tokenName' param is required Example 3: value: success: false error: 'Not Authorized [not-authorized]' errorType: not-authorized details: method: 'personalAccessTokens:generateToken' '401': $ref: '#/components/responses/authorizationError' description: |- Permission required: `create-personal-access-tokens`. * This endpoint requires two-factor authentication. * Note that the generated access tokens are irrecoverable, so storing them safely is essential. If a token is lost or forgotten, it can be regenerated or deleted. * When making calls to the API that mandate authentication, include the generated token in the `X-Auth-Token` header and your user ID in the `X-User-Id` header to authenticate the requests. Visit the Personal Access Token user guide for more details. ### Changelog | Version | Description | | ---------------- | ------------| |3.1.0 | Added `bypassTwoFactor` param | |0.69.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/x-2fa-code' - $ref: '#/components/parameters/x-2fa-method' requestBody: content: application/json: schema: type: object properties: tokenName: type: string description: The name of the token. bypassTwoFactor: type: boolean description: If 2FA requirement should be ignored when using this token. default: false required: - tokenName examples: Example 1: value: tokenName: mypersonaltoken bypassTwoFactor: false tags: - Users /api/v1/users.regeneratePersonalAccessToken: parameters: [] post: summary: Regenerate Personal Access Token operationId: post-api-v1-users.regeneratePersonalAccessToken responses: '200': description: OK content: application/json: schema: type: object properties: token: type: string success: type: boolean examples: Success Example: value: token: 2jdk99wuSjXPO201XlAks9sjDjAhSJmskAKW301mSuj9Sk success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string codeGenerated: type: boolean availableMethods: type: array items: type: object properties: {} examples: Example 1: value: success: false error: 'TOTP Required [totp-required]' errorType: totp-required details: method: password codeGenerated: false availableMethods: [] Example 2: value: success: false error: The 'tokenName' param is required Example 3: value: success: false error: 'Not Authorized [not-authorized]' errorType: not-authorized details: method: 'personalAccessTokens:generateToken' '401': $ref: '#/components/responses/authorizationError' description: |- Permission required: `create-personal-access-tokens`. This endpoint requires 2FA. ### Changelog | Version | Description | | ---------------- | ------------| |0.69.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/x-2fa-code' - $ref: '#/components/parameters/x-2fa-method' requestBody: content: application/json: schema: type: object properties: tokenName: type: string description: The name of the token. required: - tokenName examples: Example 1: value: tokenName: mypersonaltoken tags: - Users /api/v1/users.getPersonalAccessTokens: parameters: [] get: summary: Get Personal Access Tokens operationId: get-api-v1-users.getPersonalAccessTokens responses: '200': description: OK content: application/json: schema: type: object properties: tokens: type: array items: type: object properties: name: type: string createdAt: type: string lastTokenPart: type: string success: type: boolean examples: Success Example: value: tokens: - name: myToken createdAt: '2018-08-01T17:17:48.068Z' lastTokenPart: R8Agh3 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'Not Authorized [not-authorized]' errorType: not-authorized '401': $ref: '#/components/responses/authorizationError' tags: - Users description: |- Permission required: `create-personal-access-tokens` ### Changelog | Version | Description | | ---------------- | ------------| |0.69.0 | Added | parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' /api/v1/users.removePersonalAccessToken: parameters: [] post: summary: Remove Personal Access Token operationId: post-api-v1-users.removePersonalAccessToken responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string codeGenerated: type: boolean availableMethods: type: array items: type: object properties: {} examples: Example 1: value: success: false error: 'TOTP Required [totp-required]' errorType: totp-required details: method: password codeGenerated: false availableMethods: [] Example 2: value: success: false error: The 'tokenName' param is required '401': $ref: '#/components/responses/authorizationError' description: |- This endpoint requires 2FA and the `create-personal-access-tokens` permission. ### Changelog | Version | Description | | ---------------- | ------------| |0.69.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/x-2fa-code' - $ref: '#/components/parameters/x-2fa-method' tags: - Users requestBody: content: application/json: schema: type: object properties: tokenName: type: string description: The name of the token. required: - tokenName examples: Example 1: value: tokenName: mytoken /api/v1/users.requestDataDownload: get: summary: Request Data Download operationId: get-api-v1-users.requestDataDownload responses: '200': description: '' content: application/json: schema: type: object properties: requested: type: boolean exportOperation: type: object properties: _id: type: string createdAt: type: string userId: type: string roomList: type: array items: type: object properties: roomId: type: string roomName: type: string userId: type: string nullable: true exportedCount: type: integer status: type: string targetFile: type: string type: type: string status: type: string exportPath: type: string assetsPath: type: string fileList: type: array items: type: object generatedFile: type: string fullExport: type: boolean _updatedAt: type: string success: type: boolean examples: Success Example: value: requested: false exportOperation: _id: uDSuaW7vGd9B7j8qD createdAt: '2019-06-07T23:02:13.359Z' userId: hjwGZafNqExtFNmN7 roomList: - roomId: GENERAL roomName: general userId: null exportedCount: 8 status: completed targetFile: general.html type: c status: uploading exportPath: /tmp/userData/hjwGZafNqExtFNmN7/partial assetsPath: /tmp/userData/hjwGZafNqExtFNmN7/partial/assets fileList: [] generatedFile: /tmp/zipFiles/hjwGZafNqExtFNmN7.zip fullExport: false _updatedAt: '2019-06-07T23:15:00.326Z' success: true '401': $ref: '#/components/responses/authorizationError' tags: - Users parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: boolean default: false in: query name: fullExport description: >- Whether you want a full export or not. By default, the value is false. description: |- Request download of your personal data using this endpoint. The User Data Download feature must be configured in the workspace by the admin. The exported file is available in the configured directory. ### Changelog | Version | Description | | ---------------- | ------------| |1.2.0 | Added as `users.requestDataDownload` | /api/v1/users.logoutOtherClients: post: summary: Logout Other Clients operationId: post-api-v1-users.logoutOtherClients responses: '200': description: '' content: application/json: schema: type: object properties: token: type: string tokenExpires: type: string success: type: boolean examples: Success Example: value: token: SnS70r0VkngGFrSbxVK-pdwFMEzhefcjQgdnXaPeAaq tokenExpires: '2021-12-27T14:33:09.851Z' success: true '401': $ref: '#/components/responses/authorizationError' tags: - Users parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' description: | Logs out of user sessions in other clients while keeping the current session active. The response the current token and its expiration date. Requires the `LoginExpiration` settings enabled in **Accounts** > **Login Expiration in Days** which defines how long a login token remains valid before expiration. /api/v1/users.autocomplete: get: summary: Autocomplete User operationId: get-api-v1-users.autocomplete responses: '200': description: '' content: application/json: schema: type: object properties: items: type: array items: type: object properties: _id: type: string username: type: string status: type: string name: type: string nickname: type: string success: type: boolean examples: Success Example: value: items: - _id: 6esQ6cpqSQYvoLTvC username: Aaron.altamirano status: offline name: 'Aaron Altamirano ' nickname: aaron.altamirano@rocket.chat - _id: AySWYsyzToxy3239z username: Balazs.Nemethi status: offline name: Balázs Némethi - _id: gxcJTYapi5mPxuAme username: Bruno.Solis status: offline name: Bruno Solis avatarETag: ZAHMxLQ6bW426Knwm - _id: kvqbntLso8y2dEx7C username: Ivan.Belousov status: offline name: Ivan - _id: AkFjhgJFHAhNK3e6o status: offline name: Karina Monarkh username: Karina - _id: M3ajjGeyg8SfKXopd username: Rucks_guest2 status: offline name: Rucks_guest2 nickname: anonymous3 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''selector'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' description: List the users whose names match a given pattern. tags: - Users parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: object example: { "exceptions": ["john.doe"], "conditions": {"status": "offline"}, "term": "user", "$or": [{"type": "user"}, {"roles": ["bot"]}]} in: query name: selector required: true description: |- Filter the response with the parameters. /api/v1/users.removeOtherTokens: post: summary: Remove Other Tokens operationId: post-api-v1-users.removeOtherTokens responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' tags: - Users description: |- Remove user's login tokens. This endpoint is primarily used when a user changes their password and they need to log in to the workspace again on other devices. ### Changelog | Version | Description | | ---------------- | ------------| |3.1.0 | Added | /api/v1/users.resetE2EKey: post: summary: Reset Users E2E Key operationId: post-api-v1-users.resetE2EKey responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string codeGenerated: type: boolean availableMethods: type: array items: type: object properties: {} examples: Example 1: value: success: false error: 'TOTP Required [totp-required]' errorType: totp-required details: method: password codeGenerated: false availableMethods: [] Example 2: value: success: false error: 'Not allowed [error-not-allowed]' errorType: error-not-allowed Example 3: value: success: false error: >- The required "userId" or "username" param provided does not match any users [error-invalid-user] errorType: error-invalid-user '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/x-2fa-code' - $ref: '#/components/parameters/x-2fa-method' description: |- Reset the E2E key for your account or another user in the workspace. * To reset other users' E2EE key, you need the `edit-other-user-e2ee` permission. * This endpoint requires 2FA, if 2FA is enabled and configured on your workspace. ### Changelog | Version | Description | | ---------------- | ------------| |3.6.0 | Added | tags: - Users requestBody: content: application/json: schema: type: object properties: userId: type: string description: >- The `userId` of the user whose e2e key you want to reset. You can also use the `username` parameter. If you don't enter a value, the sender's E2E value is reset. examples: Example 1: value: userId: GonjPyg3gB3Z9ur9s /api/v1/users.resetTOTP: post: summary: Reset Users TOTP operationId: post-api-v1-users.resetTOTP responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string codeGenerated: type: boolean availableMethods: type: array items: type: object properties: {} examples: Example 1: value: success: false error: 'TOTP Required [totp-required]' errorType: totp-required details: method: password codeGenerated: false availableMethods: [] Example 2: value: success: false error: 'Not allowed [error-not-allowed]' errorType: error-not-allowed Example 3: value: success: false error: >- The required "userId" or "username" param provided does not match any users [error-invalid-user] errorType: error-invalid-user '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/x-2fa-code' - $ref: '#/components/parameters/x-2fa-method' description: |- Reset 2FA via TOTP for a user in the workspace. Make sure that the `Enable Two Factor Authentication` setting is enabled under **Manage** > **Workspace** > **Settings** > **Accounts** > **Two Factor Authentication**. * Permission required: `edit-other-user-totp`. * It requires two-factor authentication, if 2FA is enabled and configured in your workspace. ### Changelog | Version | Description | | ---------------- | ------------| |3.6.0 | Added | tags: - Users requestBody: content: application/json: schema: type: object properties: userId: type: string description: >- The `userId` of the user whose TOTP you want to reset. You can also use the username. If you do not enter a value, the sender's TOTP is reset. examples: Example 1: value: userId: GonjPyg3gB3Z9ur9s /api/v1/users.listTeams: get: tags: - Users summary: List User's Teams description: |- Get the list of teams that a specific user is a member of. The teams returned by the endpoint depend on your permissions. To view all teams, you need the `view-all-teams` permission. operationId: get-api-v1-users.listTeams parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: userId in: query description: The `userId` of the user. required: true schema: type: string example: rbAXPnMktTFbNpwtJ responses: '200': description: OK content: application/json: schema: type: object properties: teams: type: array items: type: object properties: _id: type: string name: type: string type: type: integer createdAt: type: string createdBy: type: object properties: _id: type: string username: type: string _updatedAt: type: string roomId: type: string isOwner: type: boolean success: type: boolean examples: Success Example: value: teams: - _id: 612b8ae982d286c3 name: documentation-team type: 0 createdAt: '2021-08-29T13:26:01.750Z' createdBy: _id: JxemcN9PDCdfzJe username: renato.b _updatedAt: '2021-08-29T13:26:01.762Z' roomId: GwktYAajqw4RiWiBK isOwner: true success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''userId'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/moderation.reportUser: post: summary: Report User operationId: post-api-v1-moderation.reportUser responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''userId'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' tags: - Users parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: userId: type: string description: The ID of the user to be reported. example: ByehQjC44FwMeiLbX description: type: string description: The reason for reporting the user. example: test required: - userId - description examples: Example 1: value: userId: ByehQjC44FwMeiLbX description: test description: |- Report a user for offensive messages in the workspace. ### Changelog | Version | Description | | ---------------- | ------------| |6.4.0 | Added | /api/v1/users.logout: post: summary: Logout User operationId: post-api-v1-users.logout responses: '200': description: OK content: application/json: schema: type: object properties: message: type: string success: type: boolean examples: Success Example: value: message: User JxemcN9PDCdfzJeZr has been logged out! success: true '401': $ref: '#/components/responses/authorizationError' tags: - Users parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' description: Log out of your account. You can also log out of another user's session. You will need the `logout-other-user` permission. requestBody: content: application/json: schema: type: object properties: userId: type: string description: Enter the user ID to be logged out. example: BsNr28znDkG8aeo7W /api/v1/ldap.syncNow: post: tags: - LDAP summary: LDAP Sync description: |-

Syncs your LDAP data based on the data sync configurations. This endpoints requires 2FA. Make sure LDAP is enabled in **Settings** > **LDAP** > **Enable** before using this endpoint. Permission required: `sync-auth-services-users`. ### Changelog | Version | Description | | ---------------- | ------------| |5.2.0 | Include `syncAvatars` | |4.0.0 | Added | operationId: post-api-v1-ldap.syncNow parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/x-2fa-code' - $ref: '#/components/parameters/x-2fa-method' responses: '200': description: OK content: application/json: schema: type: object properties: message: type: string success: type: boolean examples: Success Example: value: message: Sync_in_progress success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string codeGenerated: type: boolean availableMethods: type: array items: type: string examples: Example 1: value: success: false error: 'TOTP Required [totp-required]' errorType: totp-required details: method: totp codeGenerated: false availableMethods: - totp Example 2: value: success: false error: LDAP_disabled Example 3: value: success: false error: error-not-authorized '401': $ref: '#/components/responses/authorizationError' /api/v1/ldap.testConnection: post: tags: - LDAP summary: Test LDAP Connection description: |- Test if Rocket.Chat can connect to the specified LDAP server using the port and host provided in the Rocket.Chat settings. Make sure LDAP is enabled in **Settings** > **LDAP** > **Enable** before using this endpoint. Permission required: `test-admin-options` operationId: post-api-v1-ldap.testConnection parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' responses: '200': description: OK content: application/json: schema: type: object properties: message: type: string success: type: boolean examples: Success Example: value: message: Connection_success success: true '401': $ref: '#/components/responses/authorizationError' parameters: [] /api/v1/ldap.testSearch: post: tags: - LDAP summary: Test LDAP User Search description: |- Test if a given username can be found in the LDAP server using the authentication and filter settings provided to Rocket.Chat. Make sure LDAP is enabled in **Settings** > **LDAP** > **Enable** before using this endpoint. Permission required: `test-admin-options` operationId: post-api-v1-ldap.testSearch parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' responses: '200': description: OK content: application/json: schema: type: object properties: message: type: string success: type: boolean examples: Success Example: value: message: LDAP_User_Found success: true '400': description: Bad Request headers: {} content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: 'Match error: Missing key ''username''' '401': $ref: '#/components/responses/authorizationError' requestBody: content: application/json: schema: type: object properties: username: type: string description: The username that you want to search. example: bob required: - username examples: Example 1: value: username: bob '/api/v1/avatar/{subject}': parameters: - schema: type: string example: 'alice, @general' name: subject in: path required: true description: >- Name of the user or channel. Channels are always preceded by an `@` symbol. Rooms that are DMs are always represented by the other participant's user avatar. get: summary: Get Avatars operationId: get-api-v1-avatar-subject responses: '200': description: OK content: image/svg+xml: schema: type: string format: binary description: |- Note: * This is a RESTful endpoint that sits separately from the REST API in the server codebase and behaves slightly differently. * The `rc_uid` and `rc_token` can alternately be provided as cookies (already present in the web interface), but not as auth headers. * When requesting the avatar of a user, if they have a custom avatar set, this will override the user's choices of format or size. * If no uploaded avatar exists for a user, a default one will be generated for them based on the initial of their username in a randomly colored square. * If `UI_Use_Name_Avatar` is set and the user has a real name set, the generated avatar will be based on their actual name instead of the username. * If no format is requested, or the format requested isn't supported, the format returned will be SVG. parameters: - schema: type: string example: png in: query name: format description: >- Format of the image requested. The values can be one of: jpg, jpeg, png. - schema: type: integer example: 50 in: query name: size description: 'Width and height of the image. Default: 200' - schema: type: string example: aobEdbYhXfu5hkeqG in: query name: rc_uid description: >- User ID for authenticating is only required if `Accounts_AvatarBlockUnauthenticatedAccess` is enabled. - schema: type: string example: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq in: query name: rc_token description: >- User auth token for authenticating is only required if `Accounts_AvatarBlockUnauthenticatedAccess` is enabled. tags: - Users /api/v1/users.sendWelcomeEmail: post: tags: - Users summary: Send Welcome Email to User description: |- Ensure that you have configured the email settings in your workspace to send emails. Permission required: `send-mail` ### Changelog | Version | Description | | ------------ | ------------| |6.8.0 | Added | operationId: get-api-v1-users.sendWelcomeEmail parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: email: type: string description: The user's email address to which you want to send the welcome email. required: - email examples: Example 1: value: email: test@email.com responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: SMPT not configured: value: success: false error: 'SMTP is not configured [error-email-send-failed]' errorType: error-email-send-failed details: method: sendWelcomeEmail '401': $ref: '#/components/responses/authorizationError' /api/v1/sendInvitationEmail: post: summary: Send Invitation Email tags: - Users responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''emails'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' operationId: post-api-v1-sendInvitationEmail parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - emails properties: emails: type: array description: Enter the list of emails to which you want to send the invitation. items: type: string example: example@example.com examples: Example 1: value: emails: - example@example.com description: Send workspace invitation emails using this endpoint. /api/v1/users.sendConfirmationEmail: post: summary: Send Email Verification tags: - Users responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Missing parameter: value: success: false error: 'must have required property ''email'' [invalid-params]' errorType: invalid-params operationId: post-api-v1-users.sendConfirmationEmail description: |- Send an email to verify a user's email address. The user receives the email and they must click the confirmation button to confirm their email address. Rate limit applies: One request can be sent every 60000ms. This endpoint does not require authentication. An unverified user can call it from the login screen to resend their own verification email. ### Changelog | Version | Description | | ---------- | -------------------------------------- | | 8.6.0 | Authentication is no longer required. | requestBody: content: application/json: schema: type: object required: - email properties: email: type: string description: Enter the email address that needs to be verified. example: example@example.com examples: Example: value: email: example@example.com /api/v1/users.verifyEmail: post: tags: - Users summary: Verify User Email description: |- Verifies a user's email address using the token embedded in the verification sent to thier email. If the user has the `anonymous` role, it is replaced with the `user` role as part of the verification. ### Changelog | Version | Description | | ---------------- | ------------| |8.7.0 | Added | operationId: post-api-v1-users.verifyEmail requestBody: content: application/json: schema: type: object properties: token: type: string description: The email verification token the user received by email. example: hf5Wf4Kj9R3mR7cQ2xkPd required: - token examples: Example: value: token: hf5Wf4Kj9R3mR7cQ2xkPd responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Missing token: value: success: false error: 'must have required property ''token'' [invalid-params]' errorType: invalid-params Verification link expired: value: success: false error: Verify email link expired /api/v1/users.listByStatus: get: tags: - Users summary: List Users by Status description: |- Returns users filtered by activation status, whether they have logged in, user type, role, search term, or inactive reason. When the Premium **User status hiding** feature is enabled, users who have hidden their status from the caller remain in the response but appear as `offline`, and their detailed status fields are omitted. **Permissions required**: - `view-d-room`: View direct messages. - `view-outside-room`: View users outside the caller's rooms when `Apply_permission_view-outside-room` is enabled under **Settings** > **General** > **REST API**. ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added status visibility filtering. | |6.8.0 | Added | operationId: get-api-v1-users.listByStatus parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/count' - name: status in: query description: Filter users based on their activation status. It can either be `active` or `deactivated` schema: type: string example: active - name: hasLoggedIn in: query description: Filter the users who have logged into their accounts for the first time. schema: type: boolean example: true - name: type in: query description: 'Filter the type of users to be returned. For example, ''bot'', ''user'', ''app'', etc.' schema: type: string example: user - name: 'roles[]' in: query description: Filter the users returned based on a list of roles. schema: type: string example: bot - name: searchTerm in: query description: Filter the list of users returned based on a search term schema: type: string example: test - schema: type: string example: deactivated in: query name: 'inactiveReason[]' description: 'Filter the users based on the reason for inactive status. The options are: `idle_too_long`, `deactivated`, and `pending_approval`.' responses: '200': description: OK content: application/json: schema: type: object properties: users: type: array items: type: object properties: _id: type: string username: type: string emails: type: array items: type: object properties: address: type: string verified: type: boolean type: type: string roles: type: array items: type: string status: type: string active: type: boolean name: type: string lastLogin: type: string avatarETag: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: users: - _id: W7MRNgkYLXKKAGNvW username: agent1 emails: - address: agent1@agent.com verified: false type: user roles: - user - livechat-agent status: offline active: true name: Agent 1 lastLogin: '2024-04-24T17:47:50.485Z' - _id: Tf44Q5AaYDehtJLzA username: agent2 emails: - address: agent2@agent.com verified: false type: user roles: - user - livechat-agent status: offline active: true name: Agent 2 lastLogin: '2024-04-29T16:38:56.809Z' - _id: JwATAtGzrzHYHCXFy username: agent3 emails: - address: agent3@agent.com verified: false type: user roles: - user - livechat-agent status: online active: true name: Agent3 lastLogin: '2024-04-30T16:59:21.879Z' - _id: u6C62WdHKNk5X8Rzr username: guy emails: - address: guy@guy.com verified: false type: user roles: - user status: offline active: true name: guy - _id: rocket.cat name: Rocket.Cat username: rocket.cat status: online active: true type: bot roles: - bot avatarETag: MEhPLkenJqs3jTJP5 count: 5 offset: 0 total: 5 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/saml.parseMetadata: post: tags: - SAML summary: Parse SAML IdP Metadata description: |- Fetches and parses a SAML identity provider (IdP) metadata document from a URL. It returns the IdP certificate, sign-in URL, sign-out URL, and identifier format when those values are available in the metadata. The **Import IdP metadata** button at the top of **Manage** > **Workspace** > **Settings** > **SAML** uses this endpoint to prefill the corresponding SAML settings. The imported values can be reviewed and edited before they are saved. This endpoint does not save or change any workspace settings. The metadata request is subject to SSRF protection and the workspace's SSRF allowlist. It has a 20-second timeout and a 1 MB response-size limit. **Permission required**: - `test-admin-options` ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added | operationId: post-api-v1-saml.parseMetadata parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: type: object properties: url: type: string minLength: 1 description: The URL of the SAML IdP metadata document. example: 'https://idp.example.com/metadata' required: - url additionalProperties: false examples: Example: value: url: 'https://idp.example.com/metadata' responses: '200': description: The metadata was parsed successfully. content: application/json: schema: type: object properties: entryPoint: type: string description: The IdP URL where Rocket.Chat sends SAML sign-in requests. idpSLORedirectURL: type: string description: The IdP URL where Rocket.Chat sends SAML sign-out requests. cert: type: string description: The IdP signing certificate in PEM format. identifierFormat: type: string description: The first SAML NameID format found in the metadata. The SAML settings page applies this value when the Enterprise-only Identifier Format setting is available. warnings: type: array description: Warnings about missing or multiple usable values in the metadata. items: type: string success: type: boolean enum: - true required: - warnings - success additionalProperties: false examples: Success: value: entryPoint: 'https://idp.example.com/sso/saml' idpSLORedirectURL: 'https://idp.example.com/slo/saml' cert: |- -----BEGIN CERTIFICATE----- MIIDdzCCAl+gAwIBAgIEXAMPLEONLY -----END CERTIFICATE----- identifierFormat: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' warnings: [] success: true '400': description: The request is invalid, the metadata cannot be fetched or parsed, or the URL is blocked. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: string errorType: type: string required: - success - error examples: URL blocked: value: success: false error: SAML_Metadata_url_blocked Fetch failed: value: success: false error: SAML_Metadata_fetch_failed Metadata too large: value: success: false error: SAML_Metadata_too_large Invalid metadata: value: success: false error: SAML_Metadata_invalid '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: 'User does not have the permissions required for this action [error-unauthorized]' tags: - name: LDAP - name: Permissions - name: Roles - name: Users - name: SAML components: parameters: Auth-Token: name: X-Auth-Token in: header description: The authenticated user token. required: true schema: type: string example: RScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f UserId: name: X-User-Id in: header description: The authenticated user ID. required: true schema: type: string example: rbAXPnMktTFbNpwtJ x-2fa-code: name: x-2fa-code in: header description: >- Enter the 2FA code. This parameter is required if 2FA is enabled in your workspace. See the Introduction to Two-Factor Authentication document for details. schema: type: string example: '148750' x-2fa-method: name: x-2fa-method in: header schema: type: string description: 'Enter the method with which you get the 2FA code. It can be `email`, `totp`, or `password`. This parameter is required if 2FA is enabled in your workspace.' query: name: query in: query required: false schema: {} description: >- This parameter allows you to use [MongoDB query](https://www.mongodb.com/docs/manual/reference/operator/query/) operators to search for specific data. For example, to query users with a name that contains the letter "g": query=`{ "name": { "$regex": "g" } }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more. allowEmptyValue: false fields: name: fields in: query required: false schema: {} description: ' This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response. For example, to only retrieve the usernames of users: fields=`{ "username": 1 }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more.' offset: name: offset in: query required: false schema: type: integer example: 50 description: >- Number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more. sort: name: sort in: query required: false schema: {} description: >- List of fields to order by, and in which direction. JSON object, with properties listed in desired order, with values of 1 for ascending, or -1 for descending. For example, {"value": -1, "_id": 1}. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more. count: name: count in: query required: false schema: type: integer example: 50 description: 'How many items to return. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.' responses: authorizationError: description: Unauthorized content: application/json: schema: type: object properties: status: type: string message: type: string examples: Authorization Error: value: status: error message: You must be logged in to do this. trueSuccess: description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true