> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incredibuild.com/llms.txt
> Use this file to discover all available pages before exploring further.
# External User Management API
Last updated on Dec 22, 2025
This feature is only available in Incredibuild's [Enterprise Plan](/windows/10.35.1/pricing-plans).
You can create new users with our External User Management API. This requires an [API Key](/windows/10.35.1/api-keys) and an Enterprise license.
**Request Endpoint**
```
POST https://{IB Coordinator IP Address/Hostname}:{Web Access Port}/api/autheticationSystem?version=1.5.0
```
For example:
```
https://coordinatorPC:8000/api/autheticationSystem?version=1.5.0
```
The APi request must include a key called **client-api-key** and the value of your API key as a string. All APIs are case sensitive.
**Request Format – Setting or Updating Active Directory**
Send a PUT request, with a JSON document in the following structure, as part of the request body, similar to the following:
[Copy](javascript:void\(0\);)
```
{
"externalSystem": "LDAP", "configuration" : {
"protocol": "LDAPS",
"url": "ldaps://domain-controller-ip:636",
"rootCertificate" : "BLAH",
"bindDN": "CN=IBAdminUser,CN=Users,DC=example,DC=local",
"bindPassword": "HasambaHasambaHasamba",
"groupDN": "DC=example,DC=local",
"userDN": "CN=Users,DC=example,DC=local",
"userIdAttribute": "uid",
"groupRoles": [
{"group" : "Administrators",
"role" : " GridAdmin "} ]
}
}
```
| Field | Description | Required |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| externalSystem | The type of system to use
Always LDAP | yes |
| protocol | The LDAP protocol
Either LDAP or LDAPS | yes |
| url | The URL of the Domain Controller
ldaps\://domain-controller-ip:port or
ldap\://domain-controller-ip:port | yes |
| bindDN | The DN for the user to use when connecting to LDAP
e.g. CN=IBAdminUser,CN=Users,DC=example,DC=local | yes |
| bindPassword | The password for the user references in bindDN | yes |
| groupDN | The DN for the folder where groups are defined
e.g. DC=example,DC=local | yes |
| userDN | The DN for the folder where users are define
e.g. CN=Users,DC=example,DC=local | yes |
| rootCertificate | The certificate for the LDAPS connection
The root certificate in PEM format, with \n for new-lines, e.g.
Copy-- -- -BEGIN CERTIFICATE-- --
\nMIIDfTCCAmWgAwIBAgIQalmxCePgZIxPOujk11pN2TANBgk
qhkiG9w0BAQsFADBRMRUwEwYKCZImiZPyLGQBGRYFbG9jYWw
FjAUBgoJkiaJk/+mUMv0FEsTONai4/zL42hzTJlfwLItbv3ui
MWpYgIoQXx5dgJyp4eNDDD9t23XKbFV8qzC2WNjGZbkwhh3/6
WKkMl6Gpi+Aep2TQO0AIn745zNHI6kaKG8RmLDq+9I2K9fuQ
d/cbIe\n-----END CERTIFICATE----- | Yes, if the protocol is LDAPS |
| userIdAttribute | The attribute where the user’s UID is stored, by default uid
e.g. uid | no |
| group | The name of a group, whose users are given a role in Incredibuild
e.g. Administrators | no |
| role | The role assign to users of the above group
Either GridAdmin, GroupManager, or Viewer | no |
##### Note:
* Once set, the protocol, url and bindDN cannot be modified. Instead, disconnect from the external user management system and set it up again.
**Request Format – Setting or Updating Entra ID (Azure Active Directory)**
Send a PUT request, with a JSON document in the following structure, as part of the request body, similar to the following:
[Copy](javascript:void\(0\);)
```
{ "externalSystem" : "AZUREAD",
"configuration": {
"tenantId": "1234",
"azureAdApplicationid": "5678",
"clientSecret": "BLAH"},
"groupRoles": [
{"group": "Administrators",
"role" : " GridAdmin "}
]
}
}
```
| Field | Description | Required |
| -------------------- | -------------------------------------------------------------------------------------------- | -------- |
| externalSystem | The type of system to use
Always AZUREAD | yes |
| tenantId | The tenant ID from Azure | yes |
| azureAdApplicationid | The applicationID from Azure | yes |
| clientSecret | The name of a group, whose users are given a role in Incredibuild
e.g. Administrators | yes |
| role | The role assign to users of the above group
Either GridAdmin, GroupManager, or Viewer | yes |
**Request Format – Disconnect from External User Management System**
Send a PUT request, with a JSON document in the following structure, as part of the request body, similar to the following:
```
{ "externalSystem": "NONE" }
```
**Request Format – Show Current External User Management System**
Send a GET request, with no body. The response is in the format above, depending on the current system configured.
##### Note:
* Passwords and secrets will not appear in a GET response.