PT EN

LDAP

URL base: $BUSINESS_API

O objecto
{
  "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"
}

Obter a ligação LDAP

Registos

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).

Devolve

200 The directory connection, or null when none is configured

Erros 401 · 403

Permissões business:team:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/ldap" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Guardar a ligação LDAP

Registos

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.

Corpo application/json

namestring · opcional

Display name for the connection.

enabledboolean · opcional

Whether directory sign-in and synchronization are active. Synchronization refuses a disabled connection.

server_urlstring · obrigatório

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 · opcional

Upgrade an ldap:// connection with StartTLS before binding.

ca_certificatestring · opcional

PEM-encoded CA certificate used to verify the server's TLS certificate, when it is not publicly trusted.

bind_dnstring · opcional

Distinguished name of the service account used to search the directory.

bind_passwordstring · opcional

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 · obrigatório

Search base for user entries. Required.

user_filterstring · opcional

Extra LDAP filter clause combined with the built-in user filter, without outer parentheses.

username_attributestring · opcional

Attribute holding the sign-in name. Letters, digits, underscore and hyphen only. Defaults to sAMAccountName.

email_attributestring · opcional

Attribute holding the email address. Letters, digits, underscore and hyphen only. Defaults to mail.

name_attributestring · opcional

Attribute holding the display name. Letters, digits, underscore and hyphen only. Defaults to displayName.

group_base_dnstring · opcional

Search base for groups.

group_mappingsarray of EnterpriseLdapGroupMapping · opcional

Directory groups mapped to tenant roles.

Mostrar atributos filhos
group_dnstring · obrigatório

Distinguished name of the directory group.

rolestring · obrigatório

Tenant role granted to members of the group.

default_rolesarray of string · opcional

Roles given to synchronized users that match no group mapping. Defaults to ["operations"].

sync_interval_minutesinteger · opcional

Minutes between automatic synchronizations. Zero or negative values default to 60.

Devolve

200 The saved connection

Mostrar atributos
idstring · opcional

Connection identifier.

tenant_idstring · opcional

Tenant that owns the connection.

namestring · opcional

Display name for the connection.

enabledboolean · opcional

Whether directory sign-in and synchronization are active.

server_urlstring · opcional

Directory server address.

start_tlsboolean · opcional

Whether an ldap:// connection is upgraded with StartTLS.

ca_certificatestring · opcional

PEM-encoded CA certificate trusted for the server, when set.

bind_dnstring · opcional

Distinguished name of the service account, when set.

has_bind_passwordboolean · opcional

Whether a service account password is stored. The password itself is never returned.

base_dnstring · opcional

Search base for user entries.

user_filterstring · opcional

Extra LDAP filter clause, when set.

username_attributestring · opcional

Attribute holding the sign-in name.

email_attributestring · opcional

Attribute holding the email address.

name_attributestring · opcional

Attribute holding the display name.

group_base_dnstring · opcional

Search base for groups, when set.

group_mappingsarray of EnterpriseLdapGroupMapping · opcional

Directory groups mapped to tenant roles.

Mostrar atributos filhos
group_dnstring · obrigatório

Distinguished name of the directory group.

rolestring · obrigatório

Tenant role granted to members of the group.

default_rolesarray of string · opcional

Roles given to users that match no group mapping.

sync_interval_minutesinteger · opcional

Minutes between automatic synchronizations.

last_sync_atstring (date-time) · opcional

When the last synchronization finished, if one has run.

created_atstring (date-time) · opcional

When the connection was first saved.

updated_atstring (date-time) · opcional

When the connection was last saved.

Erros 400 · 401 · 403

Permissões business:team:manage · Funções: 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
}'
Resposta 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"
}

Remover a ligação LDAP

Registos

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.

Devolve

204 Connection removed

Erros 401 · 403 · 404

Permissões business:team:read · Funções: admin, owner

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

Connection removed

Sincronizar membros a partir do LDAP

Registos

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.

Devolve

200 Synchronization counts

Mostrar atributos
total_foundinteger · obrigatório

Directory entries returned by the search (at most 1000 per run).

createdinteger · obrigatório

Members created in the tenant.

updatedinteger · obrigatório

Existing members updated from the directory.

disabledinteger · obrigatório

Members suspended because their directory account is disabled or locked out.

duration_msinteger (int64) · obrigatório

Duration of the run, in milliseconds.

Erros 401 · 403 · 404 · 502

Permissões business:team:manage · Funções: admin, owner

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

Testar a ligação LDAP

Registos

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.

Devolve

200 Test outcome

Mostrar atributos
successboolean · obrigatório

Whether the server was reached and the service account bind (when configured) succeeded.

latency_msinteger (int64) · obrigatório

Time the test took, in milliseconds.

messagestring · obrigatório

Human-readable result, including the failure reason when success is false.

server_typestring · opcional

Server family detected from the root DSE, for example Generic LDAPv3.

Erros 401 · 403 · 404

Permissões business:team:read · Funções: admin, owner

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