> 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":{"ldap-configuration":{"type":"object","additionalProperties":false,"description":"Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body.\n","required":["loginEnabled","loginLabel","connectionUrl","allowUnauthorizedCerts","connectionSecurity","connectionPort","baseDn","bindingAdminDn","bindingAdminPassword","firstNameAttribute","lastNameAttribute","emailAttribute","loginIdAttribute","ldapIdAttribute","userFilter","synchronizationEnabled","synchronizationInterval","searchPageSize","searchTimeout","enforceEmailUniqueness"],"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":"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. 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.\n"},"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.\n"},"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.\n"}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/ldap":{"get":{"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.\n","responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldap-configuration"}}}},"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":{"ldap-configuration.update":{"type":"object","additionalProperties":false,"description":"Full LDAP configuration. Use empty strings for unset fields.","required":["loginEnabled","loginLabel","connectionUrl","allowUnauthorizedCerts","connectionSecurity","connectionPort","baseDn","bindingAdminDn","bindingAdminPassword","firstNameAttribute","lastNameAttribute","emailAttribute","loginIdAttribute","ldapIdAttribute","userFilter","synchronizationEnabled","synchronizationInterval","searchPageSize","searchTimeout","enforceEmailUniqueness"],"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.\n"},"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.\n"},"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.\n"},"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.\n"}}},"ldap-configuration":{"type":"object","additionalProperties":false,"description":"Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body.\n","required":["loginEnabled","loginLabel","connectionUrl","allowUnauthorizedCerts","connectionSecurity","connectionPort","baseDn","bindingAdminDn","bindingAdminPassword","firstNameAttribute","lastNameAttribute","emailAttribute","loginIdAttribute","ldapIdAttribute","userFilter","synchronizationEnabled","synchronizationInterval","searchPageSize","searchTimeout","enforceEmailUniqueness"],"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":"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. 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.\n"},"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.\n"},"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.\n"}}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/ldap":{"put":{"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.\n","requestBody":{"description":"The full LDAP configuration to set.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldap-configuration.update"}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldap-configuration"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```
## 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"}}},"schemas":{"ldap-sync-history.list":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ldap-sync-history"}},"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.\n"}}},"ldap-sync-history":{"type":"object","additionalProperties":false,"description":"LDAP synchronization history record.","required":["id","runMode","status","startedAt","endedAt","scanned","created","updated","disabled","error"],"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 (e.g., success, 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."}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/ldap/sync":{"get":{"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.\n","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldap-sync-history.list"}}}},"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"}},"schemas":{"ldap-sync.update":{"type":"object","additionalProperties":false,"description":"Request body for triggering an LDAP synchronization.","required":["type"],"properties":{"type":{"type":"string","enum":["live","dry"],"description":"Type of synchronization. 'live' applies changes to the database, 'dry' performs a test run without persisting changes.\n"}}},"ldap-sync-history":{"type":"object","additionalProperties":false,"description":"LDAP synchronization history record.","required":["id","runMode","status","startedAt","endedAt","scanned","created","updated","disabled","error"],"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 (e.g., success, 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."}}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/ldap/sync":{"post":{"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.\n","requestBody":{"description":"Synchronization parameters.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldap-sync.update"}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ldap-sync-history"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```