openapi: 3.2.0 info: title: n8n Public Settings Ldap API description: n8n Public API termsOfService: https://n8n.io/legal/#terms contact: email: hello@n8n.io license: name: Sustainable Use License url: https://github.com/n8n-io/n8n/blob/master/LICENSE.md version: 1.1.1 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: [] tags: - name: SettingsLdap description: Operations about LDAP settings paths: /settings/ldap: get: x-eov-operation-id: getLdapConfiguration x-required-scope: ldap:manage x-eov-operation-handler: v1/handlers/ldap/ldap.handler 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: type: object additionalProperties: false description: 'Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body. ' 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. example: false loginLabel: type: string description: Label shown on the LDAP login button. example: LDAP connectionUrl: type: string description: LDAP server URL. example: ldap://ldap.example.com allowUnauthorizedCerts: type: boolean description: Whether to allow unauthorized (self-signed) certificates. example: false connectionSecurity: type: string enum: - none - tls - startTls description: TLS/SSL security mode for the LDAP connection. example: none connectionPort: type: integer description: LDAP server port. example: 389 baseDn: type: string description: Base DN for LDAP search queries. example: dc=example,dc=com bindingAdminDn: type: string description: DN of the LDAP admin user for binding. example: cn=admin,dc=example,dc=com 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. example: givenName lastNameAttribute: type: string description: LDAP attribute mapped to the user's last name. example: sn emailAttribute: type: string description: LDAP attribute mapped to the user's email. example: mail loginIdAttribute: type: string description: LDAP attribute used for login (usually the same as emailAttribute). example: mail ldapIdAttribute: type: string description: LDAP attribute that uniquely identifies a user. example: uid userFilter: type: string description: 'Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter. ' example: (objectClass=inetOrgPerson) synchronizationEnabled: type: boolean description: Whether automatic LDAP synchronization is enabled. example: false synchronizationInterval: type: integer description: Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false. example: 60 searchPageSize: type: integer description: Number of LDAP entries to fetch per search page. example: 1000 searchTimeout: type: integer description: LDAP search timeout in seconds. example: 60 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. ' example: true '401': description: Unauthorized '403': description: Forbidden operationId: getSettingsLdap x-operation-id-source: derived put: x-eov-operation-id: updateLdapConfiguration x-required-scope: ldap:manage x-eov-operation-handler: v1/handlers/ldap/ldap.handler 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: description: The full LDAP configuration to set. required: true content: application/json: schema: 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. ' example: false loginLabel: type: string description: Label shown on the LDAP login button. example: LDAP connectionUrl: type: string description: LDAP server URL. example: ldap://ldap.example.com allowUnauthorizedCerts: type: boolean description: Whether to allow unauthorized (self-signed) certificates. example: false connectionSecurity: type: string enum: - none - tls - startTls description: TLS/SSL security mode for the LDAP connection. example: none connectionPort: type: integer description: LDAP server port. example: 389 baseDn: type: string description: Base DN for LDAP search queries. example: dc=example,dc=com bindingAdminDn: type: string description: DN of the LDAP admin user for binding. example: cn=admin,dc=example,dc=com 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. example: givenName lastNameAttribute: type: string description: LDAP attribute mapped to the user's last name. example: sn emailAttribute: type: string description: LDAP attribute mapped to the user's email. example: mail loginIdAttribute: type: string description: LDAP attribute used for login (usually the same as emailAttribute). example: mail ldapIdAttribute: type: string description: LDAP attribute that uniquely identifies a user. example: uid userFilter: type: string description: 'Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter. ' example: (objectClass=inetOrgPerson) synchronizationEnabled: type: boolean description: Whether automatic LDAP synchronization is enabled. example: false synchronizationInterval: type: integer description: Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false. example: 60 searchPageSize: type: integer description: Number of LDAP entries to fetch per search page. example: 1000 searchTimeout: type: integer description: LDAP search timeout in seconds. example: 60 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. ' example: true responses: '200': description: Operation successful. content: application/json: schema: type: object additionalProperties: false description: 'Full LDAP configuration. Every field is returned by GET; send the full object back as PUT body. ' 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. example: false loginLabel: type: string description: Label shown on the LDAP login button. example: LDAP connectionUrl: type: string description: LDAP server URL. example: ldap://ldap.example.com allowUnauthorizedCerts: type: boolean description: Whether to allow unauthorized (self-signed) certificates. example: false connectionSecurity: type: string enum: - none - tls - startTls description: TLS/SSL security mode for the LDAP connection. example: none connectionPort: type: integer description: LDAP server port. example: 389 baseDn: type: string description: Base DN for LDAP search queries. example: dc=example,dc=com bindingAdminDn: type: string description: DN of the LDAP admin user for binding. example: cn=admin,dc=example,dc=com 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. example: givenName lastNameAttribute: type: string description: LDAP attribute mapped to the user's last name. example: sn emailAttribute: type: string description: LDAP attribute mapped to the user's email. example: mail loginIdAttribute: type: string description: LDAP attribute used for login (usually the same as emailAttribute). example: mail ldapIdAttribute: type: string description: LDAP attribute that uniquely identifies a user. example: uid userFilter: type: string description: 'Additional LDAP filter to apply when searching for users. Use an empty string for no additional filter. ' example: (objectClass=inetOrgPerson) synchronizationEnabled: type: boolean description: Whether automatic LDAP synchronization is enabled. example: false synchronizationInterval: type: integer description: Interval in minutes between automatic synchronizations. Ignored if synchronizationEnabled is false. example: 60 searchPageSize: type: integer description: Number of LDAP entries to fetch per search page. example: 1000 searchTimeout: type: integer description: LDAP search timeout in seconds. example: 60 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. ' example: true '400': description: The request is invalid or provides malformed data. '401': description: Unauthorized '403': description: Forbidden operationId: putSettingsLdap x-operation-id-source: derived /settings/ldap/sync: get: x-eov-operation-id: getLdapSync x-required-scope: ldap:sync x-eov-operation-handler: v1/handlers/ldap/ldap.handler 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: - name: limit in: query description: The maximum number of items to return. required: false schema: type: number example: 100 default: 100 maximum: 250 - 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: '200': description: Operation successful. content: application/json: schema: type: object properties: data: type: array items: 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. example: 1 runMode: type: string enum: - dry - live description: Whether the sync was a dry run or applied live. example: live status: type: string description: Status of the synchronization (e.g., success, error). example: success startedAt: type: string format: date-time description: Timestamp when the synchronization started. example: 2025-07-21 10:30:00+00:00 endedAt: type: string format: date-time description: Timestamp when the synchronization completed. example: 2025-07-21 10:35:00+00:00 scanned: type: integer description: Number of LDAP entries scanned during synchronization. example: 42 created: type: integer description: Number of new users created during synchronization. example: 5 updated: type: integer description: Number of existing users updated during synchronization. example: 3 disabled: type: integer description: Number of users disabled during synchronization. example: 0 error: type: string description: Error message if the synchronization failed. Empty string if successful. example: '' nextCursor: type: - string - 'null' 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. ' example: MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA '401': description: Unauthorized '403': description: Forbidden operationId: getSettingsLdapSync x-operation-id-source: derived post: x-eov-operation-id: runLdapSync x-required-scope: ldap:sync x-eov-operation-handler: v1/handlers/ldap/ldap.handler 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. requestBody: description: Synchronization parameters. required: true content: application/json: schema: 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. ' example: live responses: '200': description: Operation successful. content: application/json: schema: 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. example: 1 runMode: type: string enum: - dry - live description: Whether the sync was a dry run or applied live. example: live status: type: string description: Status of the synchronization (e.g., success, error). example: success startedAt: type: string format: date-time description: Timestamp when the synchronization started. example: 2025-07-21 10:30:00+00:00 endedAt: type: string format: date-time description: Timestamp when the synchronization completed. example: 2025-07-21 10:35:00+00:00 scanned: type: integer description: Number of LDAP entries scanned during synchronization. example: 42 created: type: integer description: Number of new users created during synchronization. example: 5 updated: type: integer description: Number of existing users updated during synchronization. example: 3 disabled: type: integer description: Number of users disabled during synchronization. example: 0 error: type: string description: Error message if the synchronization failed. Empty string if successful. example: '' '400': description: The request is invalid or provides malformed data. '401': description: Unauthorized '403': description: Forbidden operationId: postSettingsLdapSync x-operation-id-source: derived 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 externalDocs: description: n8n API documentation url: https://docs.n8n.io/api/ x-enable-proxy: false