Ldap

Base URL: $BUSINESS_API

The object
{
  "id": "ldp_01JD3X8Q7M2N4P5R6S7T8V9W0X",
  "tenant_id": "tenant_alpha",
  "name": "Ana Matsinhe",
  "enabled": true,
  "server_url": "ldaps://dc01.example.com:636",
  "start_tls": true,
  "ca_certificate": "ca certificate",
  "bind_dn": "bind dn",
  "has_bind_password": true,
  "base_dn": "base dn",
  "user_filter": "user filter",
  "username_attribute": "username attribute",
  "email_attribute": "ana.matsinhe@example.org",
  "name_attribute": "name attribute",
  "group_base_dn": "group base dn",
  "group_mappings": [
    {
      "group_dn": "CN=Billing,OU=Groups,DC=example,DC=com",
      "role": "finance"
    }
  ],
  "default_roles": [
    "default role"
  ],
  "sync_interval_minutes": 1,
  "last_sync_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Read the tenant's directory connection

Logs

GET /ldap

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

200 The directory connection, or null when none is configured

Errors 401 · 403

Permissions business:team:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/ldap" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "ldp_01JD3X8Q7M2N4P5R6S7T8V9W0X",
  "tenant_id": "tenant_alpha",
  "name": "Ana Matsinhe",
  "enabled": true,
  "server_url": "ldaps://dc01.example.com:636",
  "start_tls": true,
  "ca_certificate": "ca certificate",
  "bind_dn": "bind dn",
  "has_bind_password": true,
  "base_dn": "base dn",
  "user_filter": "user filter",
  "username_attribute": "username attribute",
  "email_attribute": "ana.matsinhe@example.org",
  "name_attribute": "name attribute",
  "group_base_dn": "group base dn",
  "group_mappings": [
    {
      "group_dn": "CN=Billing,OU=Groups,DC=example,DC=com",
      "role": "finance"
    }
  ],
  "default_roles": [
    "default role"
  ],
  "sync_interval_minutes": 1,
  "last_sync_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Create or replace the tenant's directory connection

Logs

PUT /ldap

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

200 The 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.

created_atstring (date-time) · optional

When the connection was first saved.

updated_atstring (date-time) · optional

When the connection was last saved.

Errors 400 · 401 · 403

Permissions business:team:manage · Roles: admin, owner

curl -X PUT "$BUSINESS_API/ldap" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Head office directory",
  "enabled": true,
  "server_url": "ldaps://dc01.example.com:636",
  "start_tls": true,
  "ca_certificate": "ca certificate",
  "bind_dn": "CN=svc-sync,OU=Service,DC=example,DC=com",
  "bind_password": "bind password",
  "base_dn": "OU=Staff,DC=example,DC=com",
  "user_filter": "objectClass=user",
  "username_attribute": "sAMAccountName",
  "email_attribute": "mail",
  "name_attribute": "displayName",
  "group_base_dn": "group base dn",
  "group_mappings": [
    {
      "group_dn": "CN=Billing,OU=Groups,DC=example,DC=com",
      "role": "finance"
    }
  ],
  "default_roles": [
    "operations"
  ],
  "sync_interval_minutes": 60
}'
Response 200
{
  "id": "ldp_01JD3X8Q7M2N4P5R6S7T8V9W0X",
  "tenant_id": "tenant_alpha",
  "name": "Ana Matsinhe",
  "enabled": true,
  "server_url": "ldaps://dc01.example.com:636",
  "start_tls": true,
  "ca_certificate": "ca certificate",
  "bind_dn": "bind dn",
  "has_bind_password": true,
  "base_dn": "base dn",
  "user_filter": "user filter",
  "username_attribute": "username attribute",
  "email_attribute": "ana.matsinhe@example.org",
  "name_attribute": "name attribute",
  "group_base_dn": "group base dn",
  "group_mappings": [
    {
      "group_dn": "CN=Billing,OU=Groups,DC=example,DC=com",
      "role": "finance"
    }
  ],
  "default_roles": [
    "default role"
  ],
  "sync_interval_minutes": 1,
  "last_sync_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Remove the tenant's directory connection

Logs

DELETE /ldap

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.

Returns

204 Connection removed

Errors 401 · 403 · 404

Permissions business:team:read · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/ldap" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Connection removed

Synchronize members from the directory now

Logs

POST /ldap/sync

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

200 Synchronization 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.

duration_msinteger (int64) · required

Duration of the run, in milliseconds.

Errors 401 · 403 · 404 · 502

Permissions business:team:manage · Roles: admin, owner

curl -X POST "$BUSINESS_API/ldap/sync" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "total_found": 214,
  "created": 1,
  "updated": 1,
  "disabled": 1,
  "duration_ms": 1
}

Test connectivity to the directory server

Logs

POST /ldap/test

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

200 Test 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.

Errors 401 · 403 · 404

Permissions business:team:read · Roles: admin, owner

curl -X POST "$BUSINESS_API/ldap/test" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "success": true,
  "latency_ms": 84,
  "message": "Leitura confirmada no local.",
  "server_type": "Generic LDAPv3"
}