---
title: "PUT | Update LDAP server by [id]"
slug: "api-v2-put-update-ldap-server"
updated: 2026-11-03T14:57:57Z
published: 2026-11-03T14:57:57Z
canonical: "docs.senhasegura.io/api-v2-put-update-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.

# PUT | Update LDAP server by [id]

## Description

Replace every attribute of an LDAP/AD server connection profile in the Segura™ platform. The request carries the complete configuration, so any optional field left out is cleared.

To change a few fields and leave the rest untouched, access [PATCH | Partially update LDAP server by [id]](/v4-2/docs/api-v2-patch-update-ldap-server).

---

## 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 server's current version, read from the `ETag` header returned by [GET | List an LDAP server by [id]](/v4-2/docs/api-v2-get-list-an-ldap-server).
- The server must be active. Access [POST | Activate LDAP server](/v4-2/docs/api-v2-post-activate-ldap-server) first when it is not.

---

## Request

`PUT` `/api/v2/iam/ldap-servers/{id}`

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Unique identification code of the LDAP server. **Note:** this value is assigned by Segura™ in [POST \| Create LDAP server](/v4-2/docs/api-v2-post-create-ldap-server). |

### Headers

| Header | Required | Description |
| --- | --- | --- |
| `Content-Type` | Yes | Must be `application/json`. |
| `If-Match` | Yes | Current version of the server, as returned in the `ETag` header of the latest read. |

              Attention

              

`If-Match` is mandatory. A request without the header returns `428 Precondition Required`, and a request carrying a version that no longer matches returns `412 Precondition Failed`.

### Request body

The body takes the same fields as [POST | Create LDAP server](/v4-2/docs/api-v2-post-create-ldap-server), with the same rules.

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

              Info

              

`active`, `account_domain_name`, and `account_domain_name_short` cannot be sent. The 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 the two domain names are derived from `domain_id`.

---

### Example request

`PUT` `{{url}}/api/v2/iam/ldap-servers/7`

#### Headers

```
If-Match: "a3f8c2e1d9b04567"
```

#### Body

```
{
    "host": "ad.example.com",
    "port": 636,
    "dn_base": "CN=Users,DC=example,DC=com",
    "use_ssl": true,
    "member_is_dn": false,
    "bind_requires_dn": true,
    "account_form": "principal",
    "order": 1,
    "domain_id": 5,
    "bind_credential_id": 102,
    "use_credential_domain": false,
    "ignore_disabled_expired": true,
    "dn_bind": "CN=svc-ldap,OU=Service Accounts,DC=example,DC=com"
}
```

---

## Response

```
HTTP/1.1 200 OK
ETag: "b7c1e4f2a8d93016"
```

The `ETag` header holds the server's new version. Use it in the `If-Match` header of the next write.

### Example response body

The response carries the complete server, in the same shape as [GET | List an LDAP server by [id]](/v4-2/docs/api-v2-get-list-an-ldap-server).

```
{
    "data": {
        "id": 7,
        "ldap_server": {
            "host": "ad.example.com",
            "port": 636,
            "dn_base": "CN=Users,DC=example,DC=com",
            "active": true,
            "use_ssl": true,
            "member_is_dn": false,
            "bind_requires_dn": true,
            "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": true,
            "username_attribute": null,
            "dn_bind": "CN=svc-ldap,OU=Service Accounts,DC=example,DC=com",
            "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-12T14:03:51+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

The response fields match [GET | List an LDAP server by [id]](/v4-2/docs/api-v2-get-list-an-ldap-server).

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The updated LDAP server. |
| `data.id` | integer | Unique identification code of the server. |
| `data.ldap_server` | object | Attributes of the server, with every field returned. |
| `meta` | object | Resource metadata. |
| `meta.links.self` | string | Path of the server. |
| `meta.actions` | object | Actions available for the server in its current state. |

              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. |
| `404` | `api.resource.not_found` | The server does not exist. | Check the identification code sent in the path. |
| `409` | `api.resource.inactive` | The server is inactive, and an inactive server cannot be changed. | Activate the server with [POST \| Activate LDAP server](/v4-2/docs/api-v2-post-activate-ldap-server), then resend the request. |
| `412` | `api.precondition.failed` | The `If-Match` value does not match the server's current version, which means the server changed after it was read. | Read the server again with [GET \| List an LDAP server by [id]](/v4-2/docs/api-v2-get-list-an-ldap-server), review the changes, and resend the request with the new `ETag`. |
| `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.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 the body. |
| `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. |
| `428` | `api.precondition.required` | The request arrived without the `If-Match` header. | Read the server, then resend the request with its `ETag` value in `If-Match`. |
| `429` | `api.rate_limit.exceeded` | The request rate limit was exceeded. | Reduce the request rate and try again. |

### Example error response

`428` the request arrived without the `If-Match` header:

```
{
    "code": "api.precondition.required",
    "message": "If-Match header is required for this request.",
    "details": null
}
```

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