> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/n8n-api/settings-ldap.md).

# Settings Ldap

Operations about LDAP settings

## Retrieve the LDAP configuration

> Retrieve the current LDAP configuration, including every field exposed in the UI. The binding admin password is redacted on read. Requires the \`ldap:manage\` scope and the LDAP feature to be licensed.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsLdap","description":"Operations about LDAP settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"schemas":{"ldapConfigurationPublicDto.generated":{"type":"object","properties":{"loginEnabled":{"type":"boolean","description":"Whether LDAP login is enabled."},"loginLabel":{"type":"string","description":"Label shown on the LDAP login button."},"connectionUrl":{"type":"string","description":"LDAP server URL."},"allowUnauthorizedCerts":{"type":"boolean","description":"Whether to allow unauthorized (self-signed) certificates."},"connectionSecurity":{"type":"string","enum":["none","tls","startTls"],"description":"TLS/SSL security mode for the LDAP connection."},"connectionPort":{"type":"number","description":"LDAP server port."},"baseDn":{"type":"string","description":"Base DN for LDAP search queries."},"bindingAdminDn":{"type":"string","description":"DN of the LDAP admin user for binding."},"bindingAdminPassword":{"type":"string","description":"Password for the LDAP admin user. Redacted on GET; returns the blanking placeholder when a password is stored, empty string when unset. Send the blanking placeholder from a prior GET to keep the stored password unchanged."},"firstNameAttribute":{"type":"string","description":"LDAP attribute mapped to the user's first name."},"lastNameAttribute":{"type":"string","description":"LDAP attribute mapped to the user's last name."},"emailAttribute":{"type":"string","description":"LDAP attribute mapped to the user's email."},"loginIdAttribute":{"type":"string","description":"LDAP attribute used for login (usually the same as emailAttribute)."},"ldapIdAttribute":{"type":"string","description":"LDAP attribute that uniquely identifies a user."},"userFilter":{"type":"string","description":"Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter."},"synchronizationEnabled":{"type":"boolean","description":"Whether automatic LDAP synchronization is enabled."},"synchronizationInterval":{"type":"number","description":"Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false."},"searchPageSize":{"type":"number","description":"Number of LDAP entries to fetch per search page."},"searchTimeout":{"type":"number","description":"LDAP search timeout in seconds."},"enforceEmailUniqueness":{"type":"boolean","description":"Whether to enforce that email addresses are unique across LDAP users. When true, if two users have the same email, only the first will be imported."}},"required":["loginEnabled","loginLabel","connectionUrl","allowUnauthorizedCerts","connectionSecurity","connectionPort","baseDn","bindingAdminDn","bindingAdminPassword","firstNameAttribute","lastNameAttribute","emailAttribute","loginIdAttribute","ldapIdAttribute","userFilter","synchronizationEnabled","synchronizationInterval","searchPageSize","searchTimeout","enforceEmailUniqueness"],"description":"Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body.","additionalProperties":false}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/ldap":{"get":{"operationId":"getLdapConfiguration","tags":["SettingsLdap"],"summary":"Retrieve the LDAP configuration","description":"Retrieve the current LDAP configuration, including every field exposed in the UI. The binding admin password is redacted on read. Requires the `ldap:manage` scope and the LDAP feature to be licensed.","responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldapConfigurationPublicDto.generated"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```

## Set the LDAP configuration

> Replace the LDAP configuration with the provided full object (partial updates are not supported). For bindingAdminPassword, submit the blanking placeholder from a prior GET to keep the stored password unchanged. Requires the \`ldap:manage\` scope and the LDAP feature to be licensed. Setting loginEnabled to false is destructive and it deletes all stored LDAP user identities and disables synchronization.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsLdap","description":"Operations about LDAP settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"schemas":{"ldapConfigurationPublicDto.generated":{"type":"object","properties":{"loginEnabled":{"type":"boolean","description":"Whether LDAP login is enabled."},"loginLabel":{"type":"string","description":"Label shown on the LDAP login button."},"connectionUrl":{"type":"string","description":"LDAP server URL."},"allowUnauthorizedCerts":{"type":"boolean","description":"Whether to allow unauthorized (self-signed) certificates."},"connectionSecurity":{"type":"string","enum":["none","tls","startTls"],"description":"TLS/SSL security mode for the LDAP connection."},"connectionPort":{"type":"number","description":"LDAP server port."},"baseDn":{"type":"string","description":"Base DN for LDAP search queries."},"bindingAdminDn":{"type":"string","description":"DN of the LDAP admin user for binding."},"bindingAdminPassword":{"type":"string","description":"Password for the LDAP admin user. Redacted on GET; returns the blanking placeholder when a password is stored, empty string when unset. Send the blanking placeholder from a prior GET to keep the stored password unchanged."},"firstNameAttribute":{"type":"string","description":"LDAP attribute mapped to the user's first name."},"lastNameAttribute":{"type":"string","description":"LDAP attribute mapped to the user's last name."},"emailAttribute":{"type":"string","description":"LDAP attribute mapped to the user's email."},"loginIdAttribute":{"type":"string","description":"LDAP attribute used for login (usually the same as emailAttribute)."},"ldapIdAttribute":{"type":"string","description":"LDAP attribute that uniquely identifies a user."},"userFilter":{"type":"string","description":"Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter."},"synchronizationEnabled":{"type":"boolean","description":"Whether automatic LDAP synchronization is enabled."},"synchronizationInterval":{"type":"number","description":"Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false."},"searchPageSize":{"type":"number","description":"Number of LDAP entries to fetch per search page."},"searchTimeout":{"type":"number","description":"LDAP search timeout in seconds."},"enforceEmailUniqueness":{"type":"boolean","description":"Whether to enforce that email addresses are unique across LDAP users. When true, if two users have the same email, only the first will be imported."}},"required":["loginEnabled","loginLabel","connectionUrl","allowUnauthorizedCerts","connectionSecurity","connectionPort","baseDn","bindingAdminDn","bindingAdminPassword","firstNameAttribute","lastNameAttribute","emailAttribute","loginIdAttribute","ldapIdAttribute","userFilter","synchronizationEnabled","synchronizationInterval","searchPageSize","searchTimeout","enforceEmailUniqueness"],"description":"Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body.","additionalProperties":false}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/settings/ldap":{"put":{"operationId":"updateLdapConfiguration","tags":["SettingsLdap"],"summary":"Set the LDAP configuration","description":"Replace the LDAP configuration with the provided full object (partial updates are not supported). For bindingAdminPassword, submit the blanking placeholder from a prior GET to keep the stored password unchanged. Requires the `ldap:manage` scope and the LDAP feature to be licensed. Setting loginEnabled to false is destructive and it deletes all stored LDAP user identities and disables synchronization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"loginEnabled":{"type":"boolean","description":"Whether LDAP login is enabled. Setting this to false is destructive — it deletes all stored LDAP user identities and disables synchronization."},"loginLabel":{"type":"string","description":"Label shown on the LDAP login button."},"connectionUrl":{"type":"string","description":"LDAP server URL."},"allowUnauthorizedCerts":{"type":"boolean","description":"Whether to allow unauthorized (self-signed) certificates."},"connectionSecurity":{"type":"string","enum":["none","tls","startTls"],"description":"TLS/SSL security mode for the LDAP connection."},"connectionPort":{"type":"integer","description":"LDAP server port."},"baseDn":{"type":"string","description":"Base DN for LDAP search queries."},"bindingAdminDn":{"type":"string","description":"DN of the LDAP admin user for binding."},"bindingAdminPassword":{"type":"string","description":"Password for the LDAP admin user. To keep an existing password unchanged, submit the blanking placeholder from a prior GET response. Use an empty string to clear the password."},"firstNameAttribute":{"type":"string","description":"LDAP attribute mapped to the user's first name."},"lastNameAttribute":{"type":"string","description":"LDAP attribute mapped to the user's last name."},"emailAttribute":{"type":"string","description":"LDAP attribute mapped to the user's email."},"loginIdAttribute":{"type":"string","description":"LDAP attribute used for login (usually the same as emailAttribute)."},"ldapIdAttribute":{"type":"string","description":"LDAP attribute that uniquely identifies a user."},"userFilter":{"type":"string","description":"Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter."},"synchronizationEnabled":{"type":"boolean","description":"Whether automatic LDAP synchronization is enabled."},"synchronizationInterval":{"type":"integer","description":"Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false."},"searchPageSize":{"type":"integer","description":"Number of LDAP entries to fetch per search page."},"searchTimeout":{"type":"integer","description":"LDAP search timeout in seconds."},"enforceEmailUniqueness":{"type":"boolean","description":"Whether to enforce that email addresses are unique across LDAP users. When true, if two users have the same email, only the first will be imported."}},"required":["loginEnabled","loginLabel","connectionUrl","allowUnauthorizedCerts","connectionSecurity","connectionPort","baseDn","bindingAdminDn","bindingAdminPassword","firstNameAttribute","lastNameAttribute","emailAttribute","loginIdAttribute","ldapIdAttribute","userFilter","synchronizationEnabled","synchronizationInterval","searchPageSize","searchTimeout","enforceEmailUniqueness"],"additionalProperties":false,"description":"Full LDAP configuration. Use empty strings for unset fields."}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldapConfigurationPublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```

## Retrieve LDAP synchronization history

> Retrieve the history of LDAP synchronizations, most recent first. Requires the \`ldap:sync\` scope and the LDAP feature to be licensed.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsLdap","description":"Operations about LDAP settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first \"page\" of the collection. See pagination for more detail.","required":false,"style":"form","schema":{"type":"string"}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/ldap/sync":{"get":{"operationId":"getLdapSync","tags":["SettingsLdap"],"summary":"Retrieve LDAP synchronization history","description":"Retrieve the history of LDAP synchronizations, most recent first. Requires the `ldap:sync` scope and the LDAP feature to be licensed.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for this sync run."},"runMode":{"type":"string","enum":["dry","live"],"description":"Whether the sync was a dry run or applied live."},"status":{"type":"string","description":"Status of the synchronization (for example, success or error)."},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the synchronization started."},"endedAt":{"type":"string","format":"date-time","description":"Timestamp when the synchronization completed."},"scanned":{"type":"integer","description":"Number of LDAP entries scanned during synchronization."},"created":{"type":"integer","description":"Number of new users created during synchronization."},"updated":{"type":"integer","description":"Number of existing users updated during synchronization."},"disabled":{"type":"integer","description":"Number of users disabled during synchronization."},"error":{"type":"string","description":"Error message if the synchronization failed. Empty string if successful."}},"required":["id","runMode","status","startedAt","endedAt","scanned","created","updated","disabled","error"],"description":"LDAP synchronization history record.","additionalProperties":false}},"nextCursor":{"type":"string","nullable":true,"description":"Paginate through the synchronization history by setting the cursor parameter to the nextCursor attribute returned by the previous request. A null value means there are no more records."}},"required":["data","nextCursor"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```

## Trigger an LDAP synchronization

> Manually trigger an LDAP synchronization. The response returns the new sync history record. Requires the \`ldap:sync\` scope and the LDAP feature to be licensed.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsLdap","description":"Operations about LDAP settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"parameters":{"idempotencyKey":{"name":"Idempotency-Key","in":"header","description":"Safe retry key for this POST. Use 1 to 128 visible ASCII characters. The same key and the same request return the first successful response. A different request with this key returns 422. A retry while the first request is in progress returns 409.","required":false,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[\\x21-\\x7E]+$"}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"conflict":{"description":"Conflict"},"unsupportedMediaType":{"description":"Unsupported media type."},"unprocessableEntity":{"description":"Unprocessable Entity"}}},"paths":{"/settings/ldap/sync":{"post":{"operationId":"runLdapSync","tags":["SettingsLdap"],"summary":"Trigger an LDAP synchronization","description":"Manually trigger an LDAP synchronization. The response returns the new sync history record. Requires the `ldap:sync` scope and the LDAP feature to be licensed.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["live","dry"],"description":"Type of synchronization. 'live' applies changes to the database. 'dry' performs a test run and does not persist changes."}},"required":["type"],"additionalProperties":false,"description":"Request body for triggering an LDAP synchronization."}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for this sync run."},"runMode":{"type":"string","enum":["dry","live"],"description":"Whether the sync was a dry run or applied live."},"status":{"type":"string","description":"Status of the synchronization (for example, success or error)."},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the synchronization started."},"endedAt":{"type":"string","format":"date-time","description":"Timestamp when the synchronization completed."},"scanned":{"type":"integer","description":"Number of LDAP entries scanned during synchronization."},"created":{"type":"integer","description":"Number of new users created during synchronization."},"updated":{"type":"integer","description":"Number of existing users updated during synchronization."},"disabled":{"type":"integer","description":"Number of users disabled during synchronization."},"error":{"type":"string","description":"Error message if the synchronization failed. Empty string if successful."}},"required":["id","runMode","status","startedAt","endedAt","scanned","created","updated","disabled","error"],"description":"LDAP synchronization history record.","additionalProperties":false}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"},"415":{"$ref":"#/components/responses/unsupportedMediaType"},"422":{"$ref":"#/components/responses/unprocessableEntity"}}}}}}
```