> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.
# Test LDAP User Search
>
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`.
### Changelog
| Version | Description |
| ------- | ----------- |
| 9.0.0 | Moved to premium plans. Requires a license with the `ldap-enterprise` module. |
| 9.0.0 | Added the `LDAP_Bind_failed`, `LDAP_User_not_found`, and `LDAP_Multiple_users_found` errors. |
## OpenAPI
````json POST /api/v1/ldap.testSearch
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "User Management"
},
"servers": [
{
"url": "https://apiexplorer.support.rocket.chat"
}
],
"tags": [
{
"name": "LDAP"
},
{
"name": "Permissions"
},
{
"name": "Roles"
},
{
"name": "Users"
},
{
"name": "SAML"
}
],
"paths": {
"/api/v1/ldap.testSearch": {
"post": {
"tags": [
"LDAP"
],
"summary": "Test LDAP User Search",
"description": "\n\nTest if a given username can be found in the LDAP server using the authentication and filter settings provided to Rocket.Chat.\nMake sure LDAP is enabled in **Settings** > **LDAP** > **Enable** before using this endpoint.\n\nPermission required: `test-admin-options`.\n\n### Changelog\n| Version | Description |\n| ------- | ----------- |\n| 9.0.0 | Moved to premium plans. Requires a license with the `ldap-enterprise` module. |\n| 9.0.0 | Added the `LDAP_Bind_failed`, `LDAP_User_not_found`, and `LDAP_Multiple_users_found` errors. |",
"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"
},
"errorType": {
"type": "string"
},
"details": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "The LDAP server's error. Returned with `LDAP_Bind_failed`."
},
"total": {
"type": "string",
"description": "The number of matching users. Returned with `LDAP_Multiple_users_found`."
}
}
}
}
},
"examples": {
"Missing Username": {
"summary": "Username missing",
"description": "The request body doesn't include `username`.",
"value": {
"success": false,
"error": "must have required property 'username'",
"errorType": "error-invalid-params"
}
},
"Bind Failed": {
"summary": "LDAP bind failed",
"description": "Rocket.Chat couldn't bind to the LDAP server with the authentication user DN and password. `details.error` contains the LDAP server's error.",
"value": {
"success": false,
"error": "LDAP_Bind_failed",
"details": {
"error": "Invalid Credentials"
}
}
},
"User Not Found": {
"summary": "User not found",
"description": "No LDAP user matches the username. Wildcard characters in `username` are not expanded, so a search for `*` also returns this error.",
"value": {
"success": false,
"error": "LDAP_User_not_found"
}
},
"Multiple Users Found": {
"summary": "More than one user found",
"description": "More than one LDAP user matches the username. `details.total` contains the number of matches.",
"value": {
"success": false,
"error": "LDAP_Multiple_users_found",
"details": {
"total": "2"
}
}
},
"License Required": {
"summary": "Premium license required",
"description": "The workspace doesn't have a premium license with the `ldap-enterprise` module.",
"value": {
"success": false,
"error": "This is an enterprise feature [error-action-not-allowed]",
"errorType": "error-action-not-allowed"
}
},
"Search Failed": {
"summary": "Search failed",
"description": "The search failed for another reason, for example the LDAP server is unreachable, the base DN doesn't exist, the search filter is invalid, or `username` is empty.",
"value": {
"success": false,
"error": "LDAP_search_failed"
}
},
"LDAP Disabled": {
"summary": "LDAP is disabled",
"description": "LDAP is not enabled in the workspace (`LDAP_Enable` is off).",
"value": {
"success": false,
"error": "LDAP_disabled"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/authorizationError"
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
}
}
},
"examples": {
"Permission Error": {
"summary": "Missing permission",
"description": "The user doesn't have the `test-admin-options` permission.",
"value": {
"success": false,
"error": "User does not have the permissions required for this action [error-unauthorized]"
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
},
"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"
}
},
"responses": {
"authorizationError": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
}
}
},
"examples": {
"Authorization Error": {
"value": {
"success": false,
"error": "You must be logged in to do this."
}
}
}
}
}
}
}
}
}
````
![\"Premium](\"https://raw.githubusercontent.com/RocketChat/Rocket.Chat-Open-API/main/images/premium.svg\")