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

> ## 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 server

## Description

Create an LDAP/AD server connection profile in the Segura™ platform. A single request defines the host and port, the PAM credential used for the bind, the base DN, the account format, the evaluation order in the authentication chain, and the group query parameters.

The server is created in the active state and joins the authentication chain immediately. It is the same record the web interface manages in **Settings** > **Authentication** > **LDAP/AD**, so a server created here appears there, and the reverse.

---

## 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).
- A domain registered in the platform, to reference in `domain_id`.
- A PAM credential holding the bind account, to reference in `bind_credential_id`.

              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-servers`

### Headers

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `host` | string | Yes | Hostname or IP address of the directory server. Maximum 200 characters. |
| `port` | integer | Yes | Port the directory listens on. Allowed values: `1` to `65535`. |
| `dn_base` | string | Yes | Base distinguished name for user searches. Maximum 255 characters. |
| `use_ssl` | boolean | Yes | Enables LDAPS. |
| `member_is_dn` | boolean | Yes | Indicates that the member attribute returns a full distinguished name. |
| `bind_requires_dn` | boolean | Yes | Indicates that the directory requires a distinguished name to bind. |
| `account_form` | string | Yes | Username format the directory expects. Allowed values: `dn`, `username`, `backslash`, `principal`, `null`. |
| `order` | integer | Yes | Evaluation order in the authentication chain. The lower value is evaluated first. Must be unique among active servers. |
| `domain_id` | integer | Yes | Identification code of the domain the server belongs to. |
| `bind_credential_id` | integer | Yes | Identification code of the PAM credential used for the bind. |
| `use_credential_domain` | boolean | Yes | Uses the domain of the bind credential instead of the server's own domain. The credential must have a domain. |
| `ignore_disabled_expired` | boolean | Yes | Skips expired accounts during group synchronization. |
| `network_connector_id` | integer | No | Identification code of the network connector agent used to reach the server. Returns `null` when the server is reached directly. |
| `account_filter_format` | string | No | Custom LDAP filter used to locate an account, where `%s` is the username placeholder. Maximum 100 characters. |
| `username_attribute` | string | No | Directory attribute holding the username. Default: `uid`. Maximum 30 characters. |
| `dn_bind` | string | No | Base path used for the bind operation. Maximum 200 characters. |
| `group` | string | No | Restricts authentication to members of this group. Maximum 200 characters. |
| `group_dn` | string | No | Base distinguished name for group searches. Maximum 200 characters. |
| `group_attribute` | string | No | Directory attribute holding the group name. Maximum 200 characters. |
| `group_scope` | string | No | Scope of the group search. Allowed values: `subtree`, `onelevel`, `base`, `null`. |
| `group_filter` | string | No | LDAP filter applied when searching for groups. Maximum 200 characters. |
| `member_attribute` | string | No | Group attribute listing its members. Maximum 200 characters. |

              Attention

              

`bind_credential_id` is required. The API binds to the directory through a PAM credential, and it does not accept a user name and password sent in the request body.

Three fields cannot be sent at all. The `active` state is changed through [POST | Activate LDAP server](/v4-2/docs/api-v2-post-activate-ldap-server) and [POST | Deactivate LDAP server](/v4-2/docs/api-v2-post-deactivate-ldap-server), and `account_domain_name` and `account_domain_name_short` are derived from the domain referenced in `domain_id`. Sending any of the three returns `422 patch.field.not.allowed`.

---

### Example request

`POST` `{{url}}/api/v2/iam/ldap-servers`

#### Body

```
{
    "host": "ad.example.com",
    "port": 389,
    "dn_base": "CN=Users,DC=example,DC=com",
    "use_ssl": false,
    "member_is_dn": false,
    "bind_requires_dn": false,
    "account_form": "principal",
    "order": 1,
    "domain_id": 5,
    "bind_credential_id": 102,
    "use_credential_domain": false,
    "ignore_disabled_expired": false
}
```

---

## Response

```
HTTP/1.1 201 Created
Location: /api/v2/iam/ldap-servers/7
```

The `Location` header holds the path of the created server.

              Info

              

In version 4.2.7, the `201` response does not carry an `ETag` header. From version 4.2.10, it does, and you can use that value in `If-Match` directly. Send a [GET | List an LDAP server by [id]](/v4-2/docs/api-v2-get-list-an-ldap-server) request to the path in `Location` to read the server's current version, which [PUT | Update LDAP server by [id]](/v4-2/docs/api-v2-put-update-ldap-server) and [PATCH | Partially update LDAP server by [id]](/v4-2/docs/api-v2-patch-update-ldap-server) require in the `If-Match` header.

### Example response body

```
{
    "data": {
        "id": 7,
        "ldap_server": {
            "host": "ad.example.com",
            "port": 389,
            "dn_base": "CN=Users,DC=example,DC=com",
            "active": true,
            "use_ssl": false,
            "member_is_dn": false,
            "bind_requires_dn": false,
            "account_form": "principal",
            "order": 1,
            "domain": { "id": 5, "name": "EXAMPLE.COM" },
            "bind_credential": {
                "id": 102,
                "username": "svc-ldap@example.com",
                "domain": { "id": 5, "name": "EXAMPLE.COM" }
            },
            "network_connector": null,
            "account_filter_format": null,
            "use_credential_domain": false,
            "ignore_disabled_expired": false,
            "username_attribute": null,
            "dn_bind": null,
            "account_domain_name": "EXAMPLE.COM",
            "account_domain_name_short": "EXAMPLE",
            "group": null,
            "group_dn": null,
            "group_attribute": null,
            "group_scope": null,
            "group_filter": null,
            "member_attribute": null,
            "created_at": "2026-05-08T22:42:34+00:00",
            "updated_at": "2026-05-08T22:42:34+00:00"
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-servers/7" },
        "actions": {
            "test-connection": "/api/v2/iam/ldap-servers/7/test-connection",
            "deactivate": "/api/v2/iam/ldap-servers/7/deactivate"
        }
    }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The created LDAP server. |
| `data.id` | integer | Unique identification code of the server, assigned by Segura™. |
| `data.ldap_server` | object | Attributes of the server. |
| `data.ldap_server.host` | string | Hostname or IP address of the directory server. |
| `data.ldap_server.port` | integer | Port the directory listens on. |
| `data.ldap_server.dn_base` | string | Base distinguished name for user searches. |
| `data.ldap_server.active` | boolean | Indicates whether the server is active. A created server is always active. |
| `data.ldap_server.use_ssl` | boolean | Indicates whether LDAPS is enabled. |
| `data.ldap_server.member_is_dn` | boolean | Indicates that the member attribute returns a full distinguished name. |
| `data.ldap_server.bind_requires_dn` | boolean | Indicates that the directory requires a distinguished name to bind. |
| `data.ldap_server.account_form` | string | Username format the directory expects. |
| `data.ldap_server.order` | integer | Evaluation order in the authentication chain. |
| `data.ldap_server.domain` | object | Domain the server belongs to. Returns `null` when the stored domain name matches no registered domain. |
| `data.ldap_server.domain.id` | integer | Identification code of the domain. |
| `data.ldap_server.domain.name` | string | Name of the domain. |
| `data.ldap_server.bind_credential` | object | PAM credential used for the bind. |
| `data.ldap_server.bind_credential.id` | integer | Identification code of the credential. |
| `data.ldap_server.bind_credential.username` | string | Username of the credential. |
| `data.ldap_server.bind_credential.domain` | object | Domain of the credential. |
| `data.ldap_server.network_connector` | object | Network connector agent used to reach the server. Returns `null` when the server is reached directly. |
| `data.ldap_server.network_connector.id` | integer | Identification code of the network connector agent. |
| `data.ldap_server.network_connector.name` | string | Name of the network connector agent. |
| `data.ldap_server.account_filter_format` | string | Custom LDAP filter used to locate an account. |
| `data.ldap_server.use_credential_domain` | boolean | Indicates whether the domain of the bind credential is used. |
| `data.ldap_server.ignore_disabled_expired` | boolean | Indicates whether expired accounts are skipped during group synchronization. |
| `data.ldap_server.username_attribute` | string | Directory attribute holding the username. |
| `data.ldap_server.dn_bind` | string | Base path used for the bind operation. |
| `data.ldap_server.account_domain_name` | string | Domain name applied to accounts. Derived from the referenced domain and read-only. |
| `data.ldap_server.account_domain_name_short` | string | Short domain name applied to accounts. Derived from the referenced domain and read-only. |
| `data.ldap_server.group` | string | Group whose members are allowed to authenticate. |
| `data.ldap_server.group_dn` | string | Base distinguished name for group searches. |
| `data.ldap_server.group_attribute` | string | Directory attribute holding the group name. |
| `data.ldap_server.group_scope` | string | Scope of the group search. |
| `data.ldap_server.group_filter` | string | LDAP filter applied when searching for groups. |
| `data.ldap_server.member_attribute` | string | Group attribute listing its members. |
| `data.ldap_server.created_at` | datetime | Date and time the server was created, in ISO 8601 format. |
| `data.ldap_server.updated_at` | datetime | Date and time the server was last changed, in ISO 8601 format. |
| `meta` | object | Resource metadata. |
| `meta.links` | object | Navigation links for the created resource. |
| `meta.links.self` | string | Path of the created server. |
| `meta.actions` | object | Actions available for the server in its current state. A server created as active offers `test-connection` and `deactivate`. |

              Info

              

From version 4.2.10, the response returns `id` and the `id` of each nested object as strings, for example `"7"`. Request bodies still take these values as integers.

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `400` | `api.request.bad_request` | The request carries an unknown query parameter. | Remove the parameter and resend the request. |
| `401` | `api.auth.unauthorized` | The access token is missing or has expired. | Request a new access token. |
| `403` | `api.auth.forbidden` | The authorization does not have permission to manage LDAP servers. | Ask the administrator to check the **Users** authorization in A2A, then generate a new token. |
| `422` | `api.validation.required_field` | A required field is missing from the request body. | Add the missing field and resend the request. |
| `422` | `api.validation.invalid_type` | A field received a value of the wrong type. | Check the type expected for the field and resend the request. |
| `422` | `api.validation.port.out_of_range` | `port` is outside the range `1` to `65535`. | Send a port inside the range. |
| `422` | `api.validation.order.duplicate` | Another active server already uses this `order` value. | Send a different value, or deactivate the server that holds it. |
| `422` | `api.validation.invalid_reference` | The referenced domain, credential, or network connector does not exist. | Check the identification codes sent in `domain_id`, `bind_credential_id`, and `network_connector_id`. |
| `422` | `api.enum.invalid_value` | `account_form` or `group_scope` received a value outside its allowed list. | Check the allowed values for the field and resend the request. |
| `422` | `patch.field.not.allowed` | The body carries a read-only field, such as `active`, `account_domain_name`, or `account_domain_name_short`. | Remove the field and resend the request. |
| `429` | `api.rate_limit.exceeded` | The request rate limit was exceeded. | Reduce the request rate and try again. |

### Example error response

`422` another active server already uses the `order` value:

```
{
    "code": "api.validation.order.duplicate",
    "message": "Another active LDAP server already uses this order.",
    "details": [
        { "field": "order", "code": "api.validation.order.duplicate" }
    ]
}
```

For authentication error messages and the `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).