Returns the caller's tenant LDAP or Active Directory connection, or a JSON null body with 200 when none is configured. The service account password is never returned. Requires business:team:read (owner and admin roles hold it).
Returns
200The directory connection, or null when none is configured
Saves the caller's tenant directory settings, creating the connection on first use. A tenant has one connection; saving again replaces its settings. server_url must use ldap:// or ldaps:// and, outside development, ldap:// needs start_tls true and internal or private hosts are refused. base_dn is required; attribute names default to sAMAccountName, mail and displayName and may contain only letters, digits, underscore and hyphen. bind_password is write-only: omit it to keep the stored password; the response carries has_bind_password instead. Fields outside the input, id and tenant_id among them, are ignored, so a save always lands on the caller's own tenant. A failed validation returns 400. Requires business:team:manage and a person's session: API keys are refused with 403 api_key_not_allowed. The change is recorded in the audit log.
Body application/json
namestring · optional
Display name for the connection.
enabledboolean · optional
Whether directory sign-in and synchronization are active. Synchronization refuses a disabled connection.
server_urlstring · required
Directory server address. Must use the ldap:// or ldaps:// scheme and include a host. Outside development, ldap:// requires start_tls true, and internal host names (localhost, *.local, *.internal) and private or link-local addresses are refused.
start_tlsboolean · optional
Upgrade an ldap:// connection with StartTLS before binding.
ca_certificatestring · optional
PEM-encoded CA certificate used to verify the server's TLS certificate, when it is not publicly trusted.
bind_dnstring · optional
Distinguished name of the service account used to search the directory.
bind_passwordstring · optional
Service account password, at most 128 bytes. Write-only: it is stored encrypted and never returned; has_bind_password on a read tells whether one is set. Omit it to keep the stored password.
base_dnstring · required
Search base for user entries. Required.
user_filterstring · optional
Extra LDAP filter clause combined with the built-in user filter, without outer parentheses.
username_attributestring · optional
Attribute holding the sign-in name. Letters, digits, underscore and hyphen only. Defaults to sAMAccountName.
email_attributestring · optional
Attribute holding the email address. Letters, digits, underscore and hyphen only. Defaults to mail.
name_attributestring · optional
Attribute holding the display name. Letters, digits, underscore and hyphen only. Defaults to displayName.
group_base_dnstring · optional
Search base for groups.
group_mappingsarray of EnterpriseLdapGroupMapping · optional
Directory groups mapped to tenant roles.
Show child attributes
group_dnstring · required
Distinguished name of the directory group.
rolestring · required
Tenant role granted to members of the group.
default_rolesarray of string · optional
Roles given to synchronized users that match no group mapping. Defaults to ["operations"].
sync_interval_minutesinteger · optional
Minutes between automatic synchronizations. Zero or negative values default to 60.
Returns
200The saved connection
Show attributes
idstring · optional
Connection identifier.
tenant_idstring · optional
Tenant that owns the connection.
namestring · optional
Display name for the connection.
enabledboolean · optional
Whether directory sign-in and synchronization are active.
server_urlstring · optional
Directory server address.
start_tlsboolean · optional
Whether an ldap:// connection is upgraded with StartTLS.
ca_certificatestring · optional
PEM-encoded CA certificate trusted for the server, when set.
bind_dnstring · optional
Distinguished name of the service account, when set.
has_bind_passwordboolean · optional
Whether a service account password is stored. The password itself is never returned.
base_dnstring · optional
Search base for user entries.
user_filterstring · optional
Extra LDAP filter clause, when set.
username_attributestring · optional
Attribute holding the sign-in name.
email_attributestring · optional
Attribute holding the email address.
name_attributestring · optional
Attribute holding the display name.
group_base_dnstring · optional
Search base for groups, when set.
group_mappingsarray of EnterpriseLdapGroupMapping · optional
Directory groups mapped to tenant roles.
Show child attributes
group_dnstring · required
Distinguished name of the directory group.
rolestring · required
Tenant role granted to members of the group.
default_rolesarray of string · optional
Roles given to users that match no group mapping.
sync_interval_minutesinteger · optional
Minutes between automatic synchronizations.
last_sync_atstring (date-time) · optional
When the last synchronization finished, if one has run.
Deletes the caller's tenant directory connection. Directory sign-in and synchronization stop; members already synchronized stay. Returns 404 when no connection is configured. Requires business:team:manage (the connection is first read with business:team:read). Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Runs a synchronization against the configured directory: binds with the service account, searches base_dn (at most 1000 entries, 30 second limit) for entries with an email address, creates or updates tenant members, and suspends members whose directory account is disabled or locked out. The connection must exist and be enabled. Takes no request body. Requires business:team:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Returns
200Synchronization counts
Show attributes
total_foundinteger · required
Directory entries returned by the search (at most 1000 per run).
createdinteger · required
Members created in the tenant.
updatedinteger · required
Existing members updated from the directory.
disabledinteger · required
Members suspended because their directory account is disabled or locked out.
Connects to the configured directory server, completes the TLS handshake, binds with the service account when one is set, and reads the root DSE to identify the server. A failed connection or bind is reported in the body with success false and status 200. Takes no request body. Requires business:team:read. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Returns
200Test outcome
Show attributes
successboolean · required
Whether the server was reached and the service account bind (when configured) succeeded.
latency_msinteger (int64) · required
Time the test took, in milliseconds.
messagestring · required
Human-readable result, including the failure reason when success is false.
server_typestring · optional
Server family detected from the root DSE, for example Generic LDAPv3.