---
title: "POST | Create LDAP group sync"
slug: "api-v2-post-create-ldap-group-sync"
updated: 2026-11-03T14:57:58Z
published: 2026-11-03T14:57:58Z
canonical: "docs.senhasegura.io/api-v2-post-create-ldap-group-sync"
---

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

# POST | Create LDAP group sync

## Description

Create an LDAP group synchronization in the Segura™ platform. A single request binds an Active Directory group, identified by a distinguished name and an LDAP filter, to a user group, assigns the ACL roles its members receive, and optionally configures the Domum block.

The synchronization is created in the active state. Creating it does not import any user: run [POST | Run LDAP group sync](/v4-2/docs/api-v2-post-run-ldap-group-sync) to start the first import.

---

## Prerequisites

- An application with the **Users** authorization granted by the administrator in A2A, and its resource permission set to **Read and write**. For more information, access [How to manage authorizations in A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- The LDAP server, the user group, and any roles referenced in the request must already exist and be active.
- The `cote` license module must be active to send the `domum` block.

              Info

              

An access token carries only the authorizations that existed when it was generated. After the administrator enables the **Users** authorization, generate a new token for the application, an existing token will not gain the new authorization.

---

## Request

`POST` `/api/v2/iam/ldap-group-syncs`

### Headers

| Header | Required | Description |
| --- | --- | --- |
| `Content-Type` | Yes | Must be `application/json`. |

              Attention

              

This endpoint does not support the `Idempotency-Key` header. Retrying a request creates a second synchronization. Check whether the resource already exists with [GET | List all LDAP group syncs](/v4-2/docs/api-v2-get-list-all-ldap-group-syncs) before you retry.

### Request body

The body carries two objects. `group_sync` holds the synchronization itself, and `domum` holds the optional Domum integration.

#### `group_sync`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name of the synchronization. Maximum 100 characters. |
| `server_id` | int | Yes | Identification code of the LDAP server. The server must exist and be active. |
| `user_group_id` | int | Yes | Identification code of the user group that receives the synchronized users. The group must exist and be active. |
| `synchronization_enabled` | boolean | Yes | Indicates whether the synchronization runs. |
| `overwrite_user_accesses` | boolean | Yes | Indicates whether the synchronization overwrites the accesses already assigned to a user. Requires `synchronization_enabled` to be `true`. |
| `force_roles` | boolean | No | Indicates whether the synchronization removes from the user any role that the Active Directory group no longer grants. Default: `true`. |
| `automatic_sync` | boolean | No | Indicates whether the platform runs the synchronization on its own schedule. Default: `false`. |
| `dn` | string | Yes | Base distinguished name searched in the directory. Maximum 255 characters. |
| `ad_username_attribute` | string | Yes | Active Directory attribute read as the username. Maximum 255 characters. |
| `ad_name_attribute` | string | No | Active Directory attribute read as the full name. Allowed values: `name`, `displayname`, `samaccountname`, `null`. Values are lowercase. |
| `department_id` | int | No | Identification code of the department assigned to the synchronized users. Accepts `null`. |
| `ad_query` | string | Yes | LDAP filter that selects the groups to synchronize. Maximum 2048 characters. |
| `role_ids` | array of int | No | Identification codes of the ACL roles assigned to the synchronized users. |

#### `domum`

Send this object only when the `cote` license module is active. Without the license the request returns `422 api.feature.unavailable`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | Indicates whether the synchronized users receive Domum access. |
| `type` | string | Yes | Access profile granted in Domum. Allowed values: `full_users`, `limited_users`. |
| `vendor_id` | int | Conditional | Identification code of the vendor or internal group. Required when `enabled` is `true`. |

### Example request `POST` `{{url}}/api/v2/iam/ldap-group-syncs`

#### Body

```
{
    "group_sync": {
        "name": "Infrastructure operators",
        "server_id": 10,
        "user_group_id": 7,
        "synchronization_enabled": true,
        "overwrite_user_accesses": false,
        "force_roles": true,
        "automatic_sync": false,
        "dn": "OU=Operators,DC=example,DC=com",
        "ad_username_attribute": "sAMAccountName",
        "ad_name_attribute": "displayname",
        "ad_query": "(&(objectClass=group)(cn=ops-*))",
        "role_ids": [1, 3]
    },
    "domum": {
        "enabled": true,
        "type": "limited_users",
        "vendor_id": 22
    }
}
```

---

## Response

```
HTTP/1.1 201 Created
Location: /api/v2/iam/ldap-group-syncs/501
ETag: "174f80fa9c3b4d2e"
```

The `Location` header holds the path of the created synchronization and the `ETag` header holds its current version. Keep the `ETag` value, [PUT | Update LDAP group sync by [id]](/v4-2/docs/api-v2-put-update-ldap-group-sync), [PATCH | Partially update LDAP group sync by [id]](/v4-2/docs/api-v2-patch-update-ldap-group-sync), and [DELETE | Delete LDAP group sync by [id]](/v4-2/docs/api-v2-delete-ldap-group-sync) use it in the `If-Match` header to detect concurrent changes.

### Example response body

```
{
    "data": {
        "id": "501",
        "group_sync": {
            "name": "Infrastructure operators",
            "active": true,
            "server": { "id": "10" },
            "user_group": { "id": "7" },
            "synchronization_enabled": true,
            "overwrite_user_accesses": false,
            "force_roles": true,
            "automatic_sync": false,
            "dn": "OU=Operators,DC=example,DC=com",
            "ad_username_attribute": "sAMAccountName",
            "ad_name_attribute": "displayname",
            "department": null,
            "ad_query": "(&(objectClass=group)(cn=ops-*))",
            "roles": [{ "id": 1 }, { "id": 3 }]
        },
        "domum": {
            "enabled": true,
            "type": "limited_users",
            "vendor": { "id": 22 }
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-group-syncs/501" },
        "actions": {
            "sync": "/api/v2/iam/ldap-group-syncs/501/sync",
            "deactivate": "/api/v2/iam/ldap-group-syncs/501/deactivate"
        }
    }
}
```

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The created synchronization. |
| `meta` | object | Links and the actions available for the resource in its current state. |

### `data`

| Field | Type | Description |
| --- | --- | --- |
| →`id` | string | Unique identification code of the synchronization, assigned by Segura™. |
| →`group_sync` | object | The synchronization settings. |
| →`domum` | object | The Domum settings. Returned only when the `cote` license module is active. |

### `data.group_sync`

| Field | Type | Description |
| --- | --- | --- |
| →→`name` | string | Name of the synchronization. |
| →→`active` | boolean | Indicates whether the synchronization is active. A new synchronization is always created as `true`. |
| →→`server` | object | The LDAP server, as `{ "id": <string> }`. The request sends `server_id`. |
| →→`user_group` | object | The user group, as `{ "id": <string> }`. The request sends `user_group_id`. |
| →→`synchronization_enabled` | boolean | Indicates whether the synchronization runs. |
| →→`overwrite_user_accesses` | boolean | Indicates whether the synchronization overwrites accesses already assigned to a user. |
| →→`force_roles` | boolean | Indicates whether the synchronization removes roles the Active Directory group no longer grants. |
| →→`automatic_sync` | boolean | Indicates whether the platform runs the synchronization on its own schedule. |
| →→`dn` | string | Base distinguished name searched in the directory. |
| →→`ad_username_attribute` | string | Active Directory attribute read as the username. |
| →→`ad_name_attribute` | string | Active Directory attribute read as the full name. Returns `null` when the attribute sent is not supported. |
| →→`department` | object | The department assigned to the synchronized users. Returns `null` when not set. |
| →→`ad_query` | string | LDAP filter that selects the groups to synchronize. |
| →→`roles` | array of objects | The ACL roles assigned, each as `{ "id": <int> }`. The request sends `role_ids`. |

### `data.domum`

| Field | Type | Description |
| --- | --- | --- |
| →→`enabled` | boolean | Indicates whether the synchronized users receive Domum access. |
| →→`type` | string | Access profile granted in Domum. Returns `full_users` or `limited_users`. |
| →→`vendor` | object | The vendor or internal group, as `{ "id": <int> }`. The request sends `vendor_id`. |

              Attention

              

Sending `ad_name_attribute` with a value the platform recognizes but does not support returns `201 Created` and stores `null`. Check the `ad_name_attribute` value in the response to confirm the attribute was accepted.

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `400` | `api.request.malformed` | The body is not valid JSON. | Check the JSON syntax and resend the request. |
| `403` | `api.permission.denied` | The application lacks permission for this resource. | Ask the administrator to check the application's **Users** authorization in A2A. |
| `422` | `api.validation.required_field` | A required field is missing or `null`. | Send every required field listed in the request body tables. |
| `422` | `api.validation.invalid_type` | A field has the wrong primitive type. | Check the `Type` column in the request body tables. |
| `422` | `api.validation.length_exceeded` | A string is longer than the column allows. | Shorten the value to the maximum documented for the field. |
| `422` | `api.validation.invalid_reference` | `server_id`, `user_group_id`, `department_id`, an entry in `role_ids`, or `domum.vendor_id` does not exist. | Confirm the referenced resources exist before you resend the request. |
| `422` | `api.validation.server.inactive` | `server_id` points to an inactive LDAP server. | Activate the server, or reference an active one. |
| `422` | `api.validation.user_group.inactive` | `user_group_id` points to an inactive user group. | Activate the group, or reference an active one. |
| `422` | `api.validation.overwrite.requires_sync_enabled` | `overwrite_user_accesses` is `true` while `synchronization_enabled` is `false`. | Set `synchronization_enabled` to `true`, or set `overwrite_user_accesses` to `false`. |
| `422` | `api.validation.unknown_field` | The body carries a key that is not part of the resource schema. | Remove the key. Check that the body uses the `group_sync` and `domum` objects. |
| `422` | `api.enum.invalid_value` | `ad_name_attribute` or `domum.type` is outside its allowed values. | Send one of the allowed values listed in the request body tables. |
| `422` | `api.feature.unavailable` | The `domum` block was sent without the `cote` license module. | Remove the `domum` block, or ask the administrator to license the module. |
| `422` | `ldap_group_sync.domum.vendor_required` | `domum.enabled` is `true` without `domum.vendor_id`. | Send `domum.vendor_id`. |
| `429` | `rate_limit_exceeded` | The application exceeded its request quota. | Wait for the period in the `Retry-After` header and resend the request. |

### Authentication errors

| Message | Possible cause | Solution |
| --- | --- | --- |
| `Client authentication failed.` | Application authentication failure with the Segura server. | Check the authentication parameters (`Access Token URL`, `Client ID`, and `Client secret`) and request a new access token. |
| `Invalid signature` | Failure in recognizing the client application URL. | Check the URL of the client application and resend the request. |
| `No route matched with those values.` | Missing authorization header in the API request. | Request a new access token. |
| `Request timed out.` | The request exceeded the timeout limit. | Check the connectivity between the source of the request and the Segura server. |