> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# LDAP Connector API

Learn about the APIs for creating, retrieving, and updating LDAP Connectors.

# LDAP Connector API

version

Available since version `1.18.0`

The following APIs are provided to manage LDAP Connectors.

## Create the LDAP Connector

### Request

[!Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Create a LDAP Connector with a randomly generated Id.

POST/api/connector

OpenAPI Spec

[!Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Create a LDAP Connector with the provided unique Id.

POST/api/connector/{connectorId}

OpenAPI Spec

The **type** in the request JSON is used to determine that you are creating a LDAP Connector.

#### Request Parameters

`connectorId`UUIDoptionalDefaults to secure random UUID

The Id to use for the new Connector. If not specified a secure random UUID will be generated.

#### Request Body

`connector.authenticationURL`Stringrequired

The fully qualified LDAP URL to authenticate.

`connector.baseStructure`Stringrequired

The top of the LDAP directory hierarchy. Typically this contains the `dc` (domain component) element.

`connector.connectTimeout`Integerrequired

The connect timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.data`Objectoptional

An object that can hold any information about the Connector that should be persisted.

`connector.debug`BooleanoptionalDefaults to false

Determines if debug should be enabled to create an event log to assist in debugging integration errors.

`connector.identifyingAttribute`Stringrequired

The entry attribute name which is the first component of the distinguished name of entries in the directory.

`connector.lambdaConfiguration.reconcileId`UUIDrequired

The Id of an existing [Lambda](https://fusionauth.io/docs/apis/lambdas.md). The lambda is executed after the user authenticates with the connector. This lambda can create a user, registrations, and group memberships in FusionAuth based on attributes returned from the connector.

`connector.loginIdAttribute`Stringrequired

The entity attribute name which stores the identifier that is used for logging the user in.

`connector.name`Stringrequired

The unique LDAP Connector name.

`connector.readTimeout`Integerrequired

The read timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.requestedAttributes`required

The attributes to request for an entry from the DIT (Directory Information Tree).

`connector.securityMethod`Stringrequired

The LDAP security method. Possible values are:

*   `None` - Requests will be made without encryption.
*   `LDAPS` - A secure connection will be made to a secure port over using the LDAPS protocol.
*   `StartTLS` - An un-secured connection will initially be established, followed by secure connection established using the StartTLS extension.

`connector.systemAccountDN`Stringrequired

The distinguished name of an entry that has read access to the directory.

`connector.systemAccountPassword`Stringrequired

The password of an entry that has read access to the directory.

`connector.type`Stringrequired

This field must be set to `LDAP`.

*Example LDAP Connector Request JSON*

```json
{
  "connector": {
    "authenticationURL": "ldap://localhost:389",
    "baseStructure": "dc=mydomain,dc=org",
    "connectTimeout": 100,
    "data": {
      "modifiedBy": "richard"
    },
    "debug": true,
    "identifyingAttribute": "uid",
    "lambdaConfiguration": {
      "reconcileId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
    },
    "loginIdAttribute": "mail",
    "name": "My LDAP Connector",
    "readTimeout": 100,
    "requestedAttributes": [
      "mail",
      "uid",
      "objectClass",
      "cn",
      "employeeType",
      "labeledURI",
      "telephoneNumber"
    ],
    "securityMethod": "None",
    "systemAccountDN": "uid=admin,ou=system",
    "systemAccountPassword": "secret",
    "type": "LDAP"
  }
}
```

### Response

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body

`connector.authenticationURL`String

The fully qualified LDAP URL to authenticate.

`connector.baseStructure`String

The top of the LDAP directory hierarchy. Typically this contains the `dc` (domain component) element.

`connector.connectTimeout`Integer

The connect timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.data`Object

An object that can hold any information about the Connector that should be persisted.

`connector.debug`Boolean

Determines if debug should be enabled to create an event log to assist in debugging integration errors.

`connector.id`UUID

The unique Id of the LDAP Connector.

`connector.identifyingAttribute`String

The entry attribute name which is the first component of the distinguished name of entries in the directory.

`connector.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the LDAP Connector was created.

`connector.lambdaConfiguration.reconcileId`UUID

The Id of an existing [Lambda](https://fusionauth.io/docs/apis/lambdas.md). The lambda is executed after the user authenticates with the connector. This lambda can create a user, registrations, and group memberships in FusionAuth based on attributes returned from the connector.

`connector.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the LDAP Connector was last updated.

`connector.loginIdAttribute`String

The entity attribute name which stores the identifier that is used for logging the user in.

`connector.name`String

The unique LDAP Connector name.

`connector.readTimeout`Integer

The read timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.requestedAttributes`

The attributes to request for an entry from the DIT (Directory Information Tree).

`connector.securityMethod`String

The LDAP security method. Possible values are:

*   `None` - Requests will be made without encryption.
*   `LDAPS` - A secure connection will be made to a secure port over using the LDAPS protocol.
*   `StartTLS` - An un-secured connection will initially be established, followed by secure connection established using the StartTLS extension.

`connector.systemAccountDN`String

The distinguished name of an entry that has read access to the directory.

`connector.systemAccountPassword`String

The password of an entry that has read access to the directory.

`connector.type`String

This field must be set to `LDAP`.

*Example LDAP Connector Response JSON*

```json
{
  "connector": {
    "authenticationURL": "ldap://localhost:389",
    "baseStructure": "dc=mydomain,dc=org",
    "connectTimeout": 100,
    "data": {
      "modifiedBy": "richard"
    },
    "debug": true,
    "id": "1c212e59-0d0e-6b1a-ad48-f4f92793be32",
    "identifyingAttribute": "uid",
    "insertInstant": 1503513015493,
    "lambdaConfiguration": {
      "reconcileId": "fbd1210-2818-4353-adb2-952613eb5d96"
    },
    "lastUpdateInstant": 1503513549421,
    "loginIdAttribute": "mail",
    "name": "My LDAP Connector",
    "readTimeout": 100,
    "requestedAttributes": [
      "mail",
      "uid",
      "objectClass",
      "cn",
      "employeeType",
      "labeledURI",
      "telephoneNumber"
    ],
    "securityMethod": "None",
    "systemAccountDN": "uid=admin,ou=system",
    "systemAccountPassword": "secret",
    "type": "LDAP"
  }
}
```

## Retrieve the LDAP Connector

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Retrieve the LDAP Connector by Id

GET/api/connector/{connectorId}

OpenAPI Spec

#### Request Parameters

`connectorId`UUIDrequired

The Id of the Connector to retrieve.

### Response

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The object you requested doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body

`connector.authenticationURL`String

The fully qualified LDAP URL to authenticate.

`connector.baseStructure`String

The top of the LDAP directory hierarchy. Typically this contains the `dc` (domain component) element.

`connector.connectTimeout`Integer

The connect timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.data`Object

An object that can hold any information about the Connector that should be persisted.

`connector.debug`Boolean

Determines if debug should be enabled to create an event log to assist in debugging integration errors.

`connector.id`UUID

The unique Id of the LDAP Connector.

`connector.identifyingAttribute`String

The entry attribute name which is the first component of the distinguished name of entries in the directory.

`connector.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the LDAP Connector was created.

`connector.lambdaConfiguration.reconcileId`UUID

The Id of an existing [Lambda](https://fusionauth.io/docs/apis/lambdas.md). The lambda is executed after the user authenticates with the connector. This lambda can create a user, registrations, and group memberships in FusionAuth based on attributes returned from the connector.

`connector.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the LDAP Connector was last updated.

`connector.loginIdAttribute`String

The entity attribute name which stores the identifier that is used for logging the user in.

`connector.name`String

The unique LDAP Connector name.

`connector.readTimeout`Integer

The read timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.requestedAttributes`

The attributes to request for an entry from the DIT (Directory Information Tree).

`connector.securityMethod`String

The LDAP security method. Possible values are:

*   `None` - Requests will be made without encryption.
*   `LDAPS` - A secure connection will be made to a secure port over using the LDAPS protocol.
*   `StartTLS` - An un-secured connection will initially be established, followed by secure connection established using the StartTLS extension.

`connector.systemAccountDN`String

The distinguished name of an entry that has read access to the directory.

`connector.systemAccountPassword`String

The password of an entry that has read access to the directory.

`connector.type`String

This field must be set to `LDAP`.

*Example LDAP Connector Response JSON*

```json
{
  "connector": {
    "authenticationURL": "ldap://localhost:389",
    "baseStructure": "dc=mydomain,dc=org",
    "connectTimeout": 100,
    "data": {
      "modifiedBy": "richard"
    },
    "debug": true,
    "id": "1c212e59-0d0e-6b1a-ad48-f4f92793be32",
    "identifyingAttribute": "uid",
    "insertInstant": 1503513015493,
    "lambdaConfiguration": {
      "reconcileId": "fbd1210-2818-4353-adb2-952613eb5d96"
    },
    "lastUpdateInstant": 1503513549421,
    "loginIdAttribute": "mail",
    "name": "My LDAP Connector",
    "readTimeout": 100,
    "requestedAttributes": [
      "mail",
      "uid",
      "objectClass",
      "cn",
      "employeeType",
      "labeledURI",
      "telephoneNumber"
    ],
    "securityMethod": "None",
    "systemAccountDN": "uid=admin,ou=system",
    "systemAccountPassword": "secret",
    "type": "LDAP"
  }
}
```

## Update the LDAP Connector

This API is used to update an existing LDAP Connector.

You must specify all of the properties of the LDAP Connector when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing LDAP Connector and your new data. It replaces the existing LDAP Connector with your new data.

Utilize the `PATCH` HTTP method to send specific changes to merge into an existing LDAP Connector.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Update the LDAP Connector by Id

PUT/api/connector/{connectorId}

OpenAPI Spec

PATCH/api/connector/{connectorId}

OpenAPI Spec

note

For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior:

*   [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json`
*   [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json`

For details, see the [PATCH documentation](https://fusionauth.io/docs/apis.md#the-patch-http-method).

Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list.

#### Request Parameters

`connectorId`UUIDrequired

The Id of the Connector to update.

#### Request Body

`connector.authenticationURL`Stringrequired

The fully qualified LDAP URL to authenticate.

`connector.baseStructure`Stringrequired

The top of the LDAP directory hierarchy. Typically this contains the `dc` (domain component) element.

`connector.connectTimeout`Integerrequired

The connect timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.data`Objectoptional

An object that can hold any information about the Connector that should be persisted.

`connector.debug`BooleanoptionalDefaults to false

Determines if debug should be enabled to create an event log to assist in debugging integration errors.

`connector.identifyingAttribute`Stringrequired

The entry attribute name which is the first component of the distinguished name of entries in the directory.

`connector.lambdaConfiguration.reconcileId`UUIDrequired

The Id of an existing [Lambda](https://fusionauth.io/docs/apis/lambdas.md). The lambda is executed after the user authenticates with the connector. This lambda can create a user, registrations, and group memberships in FusionAuth based on attributes returned from the connector.

`connector.loginIdAttribute`Stringrequired

The entity attribute name which stores the identifier that is used for logging the user in.

`connector.name`Stringrequired

The unique LDAP Connector name.

`connector.readTimeout`Integerrequired

The read timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.requestedAttributes`required

The attributes to request for an entry from the DIT (Directory Information Tree).

`connector.securityMethod`Stringrequired

The LDAP security method. Possible values are:

*   `None` - Requests will be made without encryption.
*   `LDAPS` - A secure connection will be made to a secure port over using the LDAPS protocol.
*   `StartTLS` - An un-secured connection will initially be established, followed by secure connection established using the StartTLS extension.

`connector.systemAccountDN`Stringrequired

The distinguished name of an entry that has read access to the directory.

`connector.systemAccountPassword`Stringrequired

The password of an entry that has read access to the directory.

`connector.type`Stringrequired

This field must be set to `LDAP`.

*Example LDAP Connector Request JSON*

```json
{
  "connector": {
    "authenticationURL": "ldap://localhost:389",
    "baseStructure": "dc=mydomain,dc=org",
    "connectTimeout": 100,
    "data": {
      "modifiedBy": "richard"
    },
    "debug": true,
    "identifyingAttribute": "uid",
    "lambdaConfiguration": {
      "reconcileId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
    },
    "loginIdAttribute": "mail",
    "name": "My LDAP Connector",
    "readTimeout": 100,
    "requestedAttributes": [
      "mail",
      "uid",
      "objectClass",
      "cn",
      "employeeType",
      "labeledURI",
      "telephoneNumber"
    ],
    "securityMethod": "None",
    "systemAccountDN": "uid=admin,ou=system",
    "systemAccountPassword": "secret",
    "type": "LDAP"
  }
}
```

### Response

The response for this API contains the LDAP Connector.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The object you are trying to update doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body

`connector.authenticationURL`String

The fully qualified LDAP URL to authenticate.

`connector.baseStructure`String

The top of the LDAP directory hierarchy. Typically this contains the `dc` (domain component) element.

`connector.connectTimeout`Integer

The connect timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.data`Object

An object that can hold any information about the Connector that should be persisted.

`connector.debug`Boolean

Determines if debug should be enabled to create an event log to assist in debugging integration errors.

`connector.id`UUID

The unique Id of the LDAP Connector.

`connector.identifyingAttribute`String

The entry attribute name which is the first component of the distinguished name of entries in the directory.

`connector.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the LDAP Connector was created.

`connector.lambdaConfiguration.reconcileId`UUID

The Id of an existing [Lambda](https://fusionauth.io/docs/apis/lambdas.md). The lambda is executed after the user authenticates with the connector. This lambda can create a user, registrations, and group memberships in FusionAuth based on attributes returned from the connector.

`connector.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the LDAP Connector was last updated.

`connector.loginIdAttribute`String

The entity attribute name which stores the identifier that is used for logging the user in.

`connector.name`String

The unique LDAP Connector name.

`connector.readTimeout`Integer

The read timeout for the HTTP connection, in milliseconds. Value must be greater than `0`.

`connector.requestedAttributes`

The attributes to request for an entry from the DIT (Directory Information Tree).

`connector.securityMethod`String

The LDAP security method. Possible values are:

*   `None` - Requests will be made without encryption.
*   `LDAPS` - A secure connection will be made to a secure port over using the LDAPS protocol.
*   `StartTLS` - An un-secured connection will initially be established, followed by secure connection established using the StartTLS extension.

`connector.systemAccountDN`String

The distinguished name of an entry that has read access to the directory.

`connector.systemAccountPassword`String

The password of an entry that has read access to the directory.

`connector.type`String

This field must be set to `LDAP`.

*Example LDAP Connector Response JSON*

```json
{
  "connector": {
    "authenticationURL": "ldap://localhost:389",
    "baseStructure": "dc=mydomain,dc=org",
    "connectTimeout": 100,
    "data": {
      "modifiedBy": "richard"
    },
    "debug": true,
    "id": "1c212e59-0d0e-6b1a-ad48-f4f92793be32",
    "identifyingAttribute": "uid",
    "insertInstant": 1503513015493,
    "lambdaConfiguration": {
      "reconcileId": "fbd1210-2818-4353-adb2-952613eb5d96"
    },
    "lastUpdateInstant": 1503513549421,
    "loginIdAttribute": "mail",
    "name": "My LDAP Connector",
    "readTimeout": 100,
    "requestedAttributes": [
      "mail",
      "uid",
      "objectClass",
      "cn",
      "employeeType",
      "labeledURI",
      "telephoneNumber"
    ],
    "securityMethod": "None",
    "systemAccountDN": "uid=admin,ou=system",
    "systemAccountPassword": "secret",
    "type": "LDAP"
  }
}
```

## Delete the LDAP Connector

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Delete the LDAP Connector by Id

DELETE/api/connector/{connectorId}

OpenAPI Spec

`connectorId`UUIDrequired

The Id of the Connector to delete.

### Response

This API does not return a JSON response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The object you requested doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |