For the complete documentation index, see llms.txt. This page is also available as Markdown.

Settings Ldap

Operations about LDAP settings

Retrieve the LDAP configuration

get
/settings/ldap

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.

Authorizations
X-N8N-API-KEYstringRequired
Responses
200

Operation successful.

application/json

Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body.

loginEnabledbooleanRequired

Whether LDAP login is enabled.

Example: false
loginLabelstringRequired

Label shown on the LDAP login button.

Example: LDAP
connectionUrlstringRequired

LDAP server URL.

Example: ldap://ldap.example.com
allowUnauthorizedCertsbooleanRequired

Whether to allow unauthorized (self-signed) certificates.

Example: false
connectionSecuritystring · enumRequired

TLS/SSL security mode for the LDAP connection.

Example: nonePossible values:
connectionPortintegerRequired

LDAP server port.

Example: 389
baseDnstringRequired

Base DN for LDAP search queries.

Example: dc=example,dc=com
bindingAdminDnstringRequired

DN of the LDAP admin user for binding.

Example: cn=admin,dc=example,dc=com
bindingAdminPasswordstringRequired

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.

firstNameAttributestringRequired

LDAP attribute mapped to the user's first name.

Example: givenName
lastNameAttributestringRequired

LDAP attribute mapped to the user's last name.

Example: sn
emailAttributestringRequired

LDAP attribute mapped to the user's email.

Example: mail
loginIdAttributestringRequired

LDAP attribute used for login (usually the same as emailAttribute).

Example: mail
ldapIdAttributestringRequired

LDAP attribute that uniquely identifies a user.

Example: uid
userFilterstringRequired

Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter.

Example: (objectClass=inetOrgPerson)
synchronizationEnabledbooleanRequired

Whether automatic LDAP synchronization is enabled.

Example: false
synchronizationIntervalintegerRequired

Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false.

Example: 60
searchPageSizeintegerRequired

Number of LDAP entries to fetch per search page.

Example: 1000
searchTimeoutintegerRequired

LDAP search timeout in seconds.

Example: 60
enforceEmailUniquenessbooleanRequired

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.

Example: true
get/settings/ldap
GET /api/v1/settings/ldap HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*
{
  "loginEnabled": false,
  "loginLabel": "LDAP",
  "connectionUrl": "ldap://ldap.example.com",
  "allowUnauthorizedCerts": false,
  "connectionSecurity": "none",
  "connectionPort": 389,
  "baseDn": "dc=example,dc=com",
  "bindingAdminDn": "cn=admin,dc=example,dc=com",
  "bindingAdminPassword": "text",
  "firstNameAttribute": "givenName",
  "lastNameAttribute": "sn",
  "emailAttribute": "mail",
  "loginIdAttribute": "mail",
  "ldapIdAttribute": "uid",
  "userFilter": "(objectClass=inetOrgPerson)",
  "synchronizationEnabled": false,
  "synchronizationInterval": 60,
  "searchPageSize": 1000,
  "searchTimeout": 60,
  "enforceEmailUniqueness": true
}

Set the LDAP configuration

put
/settings/ldap

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.

Authorizations
X-N8N-API-KEYstringRequired
Body

Full LDAP configuration. Use empty strings for unset fields.

loginEnabledbooleanRequired

Whether LDAP login is enabled. Setting this to false is destructive — it deletes all stored LDAP user identities and disables synchronization.

Example: false
loginLabelstringRequired

Label shown on the LDAP login button.

Example: LDAP
connectionUrlstringRequired

LDAP server URL.

Example: ldap://ldap.example.com
allowUnauthorizedCertsbooleanRequired

Whether to allow unauthorized (self-signed) certificates.

Example: false
connectionSecuritystring · enumRequired

TLS/SSL security mode for the LDAP connection.

Example: nonePossible values:
connectionPortintegerRequired

LDAP server port.

Example: 389
baseDnstringRequired

Base DN for LDAP search queries.

Example: dc=example,dc=com
bindingAdminDnstringRequired

DN of the LDAP admin user for binding.

Example: cn=admin,dc=example,dc=com
bindingAdminPasswordstringRequired

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.

firstNameAttributestringRequired

LDAP attribute mapped to the user's first name.

Example: givenName
lastNameAttributestringRequired

LDAP attribute mapped to the user's last name.

Example: sn
emailAttributestringRequired

LDAP attribute mapped to the user's email.

Example: mail
loginIdAttributestringRequired

LDAP attribute used for login (usually the same as emailAttribute).

Example: mail
ldapIdAttributestringRequired

LDAP attribute that uniquely identifies a user.

Example: uid
userFilterstringRequired

Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter.

Example: (objectClass=inetOrgPerson)
synchronizationEnabledbooleanRequired

Whether automatic LDAP synchronization is enabled.

Example: false
synchronizationIntervalintegerRequired

Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false.

Example: 60
searchPageSizeintegerRequired

Number of LDAP entries to fetch per search page.

Example: 1000
searchTimeoutintegerRequired

LDAP search timeout in seconds.

Example: 60
enforceEmailUniquenessbooleanRequired

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.

Example: true
Responses
200

Operation successful.

application/json

Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body.

loginEnabledbooleanRequired

Whether LDAP login is enabled.

Example: false
loginLabelstringRequired

Label shown on the LDAP login button.

Example: LDAP
connectionUrlstringRequired

LDAP server URL.

Example: ldap://ldap.example.com
allowUnauthorizedCertsbooleanRequired

Whether to allow unauthorized (self-signed) certificates.

Example: false
connectionSecuritystring · enumRequired

TLS/SSL security mode for the LDAP connection.

Example: nonePossible values:
connectionPortintegerRequired

LDAP server port.

Example: 389
baseDnstringRequired

Base DN for LDAP search queries.

Example: dc=example,dc=com
bindingAdminDnstringRequired

DN of the LDAP admin user for binding.

Example: cn=admin,dc=example,dc=com
bindingAdminPasswordstringRequired

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.

firstNameAttributestringRequired

LDAP attribute mapped to the user's first name.

Example: givenName
lastNameAttributestringRequired

LDAP attribute mapped to the user's last name.

Example: sn
emailAttributestringRequired

LDAP attribute mapped to the user's email.

Example: mail
loginIdAttributestringRequired

LDAP attribute used for login (usually the same as emailAttribute).

Example: mail
ldapIdAttributestringRequired

LDAP attribute that uniquely identifies a user.

Example: uid
userFilterstringRequired

Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter.

Example: (objectClass=inetOrgPerson)
synchronizationEnabledbooleanRequired

Whether automatic LDAP synchronization is enabled.

Example: false
synchronizationIntervalintegerRequired

Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false.

Example: 60
searchPageSizeintegerRequired

Number of LDAP entries to fetch per search page.

Example: 1000
searchTimeoutintegerRequired

LDAP search timeout in seconds.

Example: 60
enforceEmailUniquenessbooleanRequired

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.

Example: true
put/settings/ldap
PUT /api/v1/settings/ldap HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 575

{
  "loginEnabled": false,
  "loginLabel": "LDAP",
  "connectionUrl": "ldap://ldap.example.com",
  "allowUnauthorizedCerts": false,
  "connectionSecurity": "none",
  "connectionPort": 389,
  "baseDn": "dc=example,dc=com",
  "bindingAdminDn": "cn=admin,dc=example,dc=com",
  "bindingAdminPassword": "text",
  "firstNameAttribute": "givenName",
  "lastNameAttribute": "sn",
  "emailAttribute": "mail",
  "loginIdAttribute": "mail",
  "ldapIdAttribute": "uid",
  "userFilter": "(objectClass=inetOrgPerson)",
  "synchronizationEnabled": false,
  "synchronizationInterval": 60,
  "searchPageSize": 1000,
  "searchTimeout": 60,
  "enforceEmailUniqueness": true
}
{
  "loginEnabled": false,
  "loginLabel": "LDAP",
  "connectionUrl": "ldap://ldap.example.com",
  "allowUnauthorizedCerts": false,
  "connectionSecurity": "none",
  "connectionPort": 389,
  "baseDn": "dc=example,dc=com",
  "bindingAdminDn": "cn=admin,dc=example,dc=com",
  "bindingAdminPassword": "text",
  "firstNameAttribute": "givenName",
  "lastNameAttribute": "sn",
  "emailAttribute": "mail",
  "loginIdAttribute": "mail",
  "ldapIdAttribute": "uid",
  "userFilter": "(objectClass=inetOrgPerson)",
  "synchronizationEnabled": false,
  "synchronizationInterval": 60,
  "searchPageSize": 1000,
  "searchTimeout": 60,
  "enforceEmailUniqueness": true
}

Retrieve LDAP synchronization history

get
/settings/ldap/sync

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

Authorizations
X-N8N-API-KEYstringRequired
Query parameters
limitnumber · max: 250Optional

The maximum number of items to return.

Default: 100Example: 100
cursorstringOptional

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.

Responses
200

Operation successful.

application/json
nextCursorstring · nullableOptional

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.

Example: MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
get/settings/ldap/sync
GET /api/v1/settings/ldap/sync HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*
{
  "data": [
    {
      "id": 1,
      "runMode": "live",
      "status": "success",
      "startedAt": "2025-07-21T10:30:00Z",
      "endedAt": "2025-07-21T10:35:00Z",
      "scanned": 42,
      "created": 5,
      "updated": 3,
      "disabled": 0,
      "error": ""
    }
  ],
  "nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}

Trigger an LDAP synchronization

post
/settings/ldap/sync

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.

Authorizations
X-N8N-API-KEYstringRequired
Body

Request body for triggering an LDAP synchronization.

typestring · enumRequired

Type of synchronization. 'live' applies changes to the database, 'dry' performs a test run without persisting changes.

Example: livePossible values:
Responses
200

Operation successful.

application/json

LDAP synchronization history record.

idintegerRequired

Unique identifier for this sync run.

Example: 1
runModestring · enumRequired

Whether the sync was a dry run or applied live.

Example: livePossible values:
statusstringRequired

Status of the synchronization (e.g., success, error).

Example: success
startedAtstring · date-timeRequired

Timestamp when the synchronization started.

Example: 2025-07-21T10:30:00Z
endedAtstring · date-timeRequired

Timestamp when the synchronization completed.

Example: 2025-07-21T10:35:00Z
scannedintegerRequired

Number of LDAP entries scanned during synchronization.

Example: 42
createdintegerRequired

Number of new users created during synchronization.

Example: 5
updatedintegerRequired

Number of existing users updated during synchronization.

Example: 3
disabledintegerRequired

Number of users disabled during synchronization.

Example: 0
errorstringRequired

Error message if the synchronization failed. Empty string if successful.

post/settings/ldap/sync
POST /api/v1/settings/ldap/sync HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "type": "live"
}
{
  "id": 1,
  "runMode": "live",
  "status": "success",
  "startedAt": "2025-07-21T10:30:00Z",
  "endedAt": "2025-07-21T10:35:00Z",
  "scanned": 42,
  "created": 5,
  "updated": 3,
  "disabled": 0,
  "error": ""
}

Last updated

Was this helpful?