> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Directories

> Sync Essal Access with LDAP directories or Active Directory and map groups to Essal roles.

Essal Access can sync with your existing corporate directory — LDAP or Microsoft Active Directory — to automatically reflect your organisational structure in the platform.

## Directory Sync Overview

Directory sync is a one-way pull from your directory server into Essal. Essal reads users and groups from the directory on a configurable schedule and reconciles them against existing Access users.

Sync operations:

* **Create**: New directory users are provisioned in Essal
* **Update**: Changed attributes (name, email, department) are reflected
* **Deactivate**: Users removed from the directory are suspended in Essal
* **Group sync**: Directory groups are mapped to Essal roles

## Configuring an LDAP Connection

```bash theme={null}
POST /v1/access/directories
{
  "type": "ldap",
  "name": "Acme Corp LDAP",
  "host": "ldap.acme-corp.com",
  "port": 636,
  "use_tls": true,
  "bind_dn": "cn=essal-sync,dc=acme-corp,dc=com",
  "bind_password": "REDACTED",
  "user_search_base": "ou=people,dc=acme-corp,dc=com",
  "user_search_filter": "(objectClass=inetOrgPerson)",
  "group_search_base": "ou=groups,dc=acme-corp,dc=com"
}
```

<Warning>
  Store your `bind_password` in a secrets manager. Never include it directly in application code or commit it to source control.
</Warning>

## Configuring Active Directory

For Active Directory, use the `active_directory` type and provide the domain:

```bash theme={null}
POST /v1/access/directories
{
  "type": "active_directory",
  "name": "Acme AD",
  "host": "ad.acme-corp.com",
  "port": 636,
  "use_tls": true,
  "domain": "acme-corp.com",
  "bind_dn": "ACME\\essal-sync",
  "bind_password": "REDACTED"
}
```

## Group Mapping

Map directory groups to Essal roles so that group membership in your directory automatically grants the corresponding app access in Essal:

```bash theme={null}
POST /v1/access/directories/dir_01HXYZDIR1/group-mappings
{
  "mappings": [
    { "directory_group": "CN=Editors,OU=Groups,DC=acme-corp,DC=com", "essal_role": "office:editor" },
    { "directory_group": "CN=Sales Team,OU=Groups,DC=acme-corp,DC=com", "essal_role": "sales:rep" },
    { "directory_group": "CN=IT Admins,OU=Groups,DC=acme-corp,DC=com", "essal_role": "workspace:admin" }
  ]
}
```

## Sync Schedule and Manual Sync

By default, Essal syncs with the directory every 4 hours. You can adjust the schedule or trigger an immediate sync:

```bash theme={null}
# Adjust sync interval (in minutes)
PATCH /v1/access/directories/dir_01HXYZDIR1
{ "sync_interval_minutes": 60 }

# Trigger immediate sync
POST /v1/access/directories/dir_01HXYZDIR1/sync
```

The sync job runs asynchronously. Poll `GET /v1/access/directories/dir_01HXYZDIR1/sync/latest` to check its status and review any errors.