---
title: "PUT | Atualizar servidor LDAP por [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 | Atualizar servidor LDAP por [id]

## Descrição

Substitua todos os atributos de um perfil de conexão de servidor LDAP/AD na plataforma Segura™. A requisição carrega a configuração completa, então qualquer campo opcional deixado de fora é limpo.

Para alterar apenas alguns campos e deixar o restante intocado, acesse [PATCH | Atualizar parcialmente servidor LDAP por [id]](/v4-2/docs/api-v2-patch-update-ldap-server).

---

## Pré-requisitos

- Uma aplicação com a autorização **Users** concedida pelo administrador no A2A, com a permissão do recurso definida como **Leitura e escrita**. Para mais informações, acesse [Como gerenciar autorizações no A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a).
- Um token de acesso OAuth 2.0 válido. Para mais informações, acesse [Como autenticar uma aplicação A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- A versão atual do servidor, lida no cabeçalho `ETag` retornado por [GET | Listar um servidor LDAP por [id]](/v4-2/docs/api-v2-get-list-an-ldap-server).
- O servidor deve estar ativo. Acesse [POST | Ativar servidor LDAP](/v4-2/docs/api-v2-post-activate-ldap-server) primeiro quando não estiver.

---

## Requisição

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

### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | integer | Sim | Código de identificação único do servidor LDAP. **Nota:** este valor é atribuído pela Segura™ em [POST \| Criar servidor LDAP](/v4-2/docs/api-v2-post-create-ldap-server). |

### Cabeçalhos

| Cabeçalho | Obrigatório | Descrição |
| --- | --- | --- |
| `Content-Type` | Sim | Deve ser `application/json`. |
| `If-Match` | Sim | Versão atual do servidor, conforme retornada no cabeçalho `ETag` da última leitura. |

              Atenção

              

`If-Match` é obrigatório. Uma requisição sem o cabeçalho retorna `428 Precondition Required`, e uma requisição carregando uma versão que não corresponde mais retorna `412 Precondition Failed`.

### Corpo da requisição

O corpo recebe os mesmos campos de [POST | Criar servidor LDAP](/v4-2/docs/api-v2-post-create-ldap-server), com as mesmas regras.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `host` | string | Sim | Hostname ou endereço IP do servidor de diretório. Máximo de 200 caracteres. |
| `port` | integer | Sim | Porta em que o diretório escuta. Valores permitidos: `1` a `65535`. |
| `dn_base` | string | Sim | DN base para buscas de usuário. Máximo de 255 caracteres. |
| `use_ssl` | boolean | Sim | Habilita o LDAPS. |
| `member_is_dn` | boolean | Sim | Indica que o atributo de membro retorna uma DN completa. |
| `bind_requires_dn` | boolean | Sim | Indica que o diretório exige uma DN para o bind. |
| `account_form` | string | Sim | Formato de usuário esperado pelo diretório. Valores permitidos: `dn`, `username`, `backslash`, `principal`, `null`. |
| `order` | integer | Sim | Ordem de avaliação na cadeia de autenticação. Deve ser único entre os servidores ativos. |
| `domain_id` | integer | Sim | Código de identificação do domínio ao qual o servidor pertence. |
| `bind_credential_id` | integer | Sim | Código de identificação da credencial PAM usada no bind. |
| `use_credential_domain` | boolean | Sim | Usa o domínio da credencial de bind em vez do domínio próprio do servidor. |
| `ignore_disabled_expired` | boolean | Sim | Ignora contas expiradas durante a sincronização de grupo. |
| `network_connector_id` | integer | Não | Código de identificação do agente de network connector usado para alcançar o servidor. |
| `account_filter_format` | string | Não | Filtro LDAP customizado usado para localizar uma conta, em que `%s` é o placeholder do nome de usuário. Máximo de 100 caracteres. |
| `username_attribute` | string | Não | Atributo do diretório que contém o nome de usuário. Padrão: `uid`. Máximo de 30 caracteres. |
| `dn_bind` | string | Não | Caminho base usado na operação de bind. Máximo de 200 caracteres. |
| `group` | string | Não | Restringe a autenticação aos membros deste grupo. Máximo de 200 caracteres. |
| `group_dn` | string | Não | DN base para buscas de grupo. Máximo de 200 caracteres. |
| `group_attribute` | string | Não | Atributo do diretório que contém o nome do grupo. Máximo de 200 caracteres. |
| `group_scope` | string | Não | Escopo da busca de grupo. Valores permitidos: `subtree`, `onelevel`, `base`, `null`. |
| `group_filter` | string | Não | Filtro LDAP aplicado ao buscar grupos. Máximo de 200 caracteres. |
| `member_attribute` | string | Não | Atributo do grupo que lista seus membros. Máximo de 200 caracteres. |

              Info

              

`active`, `account_domain_name` e `account_domain_name_short` não podem ser enviados. O estado é alterado por meio de [POST | Ativar servidor LDAP](/v4-2/docs/api-v2-post-activate-ldap-server) e [POST | Desativar servidor LDAP](/v4-2/docs/api-v2-post-deactivate-ldap-server), e os dois nomes de domínio são derivados de `domain_id`.

---

### Exemplo de requisição

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

#### Cabeçalhos

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

#### Corpo

```
{
    "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"
}
```

---

## Resposta

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

O cabeçalho `ETag` contém a nova versão do servidor. Use o valor no cabeçalho `If-Match` da próxima escrita.

### Exemplo de corpo da resposta

A resposta carrega o servidor completo, no mesmo formato de [GET | Listar um servidor LDAP por [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"
        }
    }
}
```

---

## Campos do corpo da resposta

Os campos da resposta correspondem aos de [GET | Listar um servidor LDAP por [id]](/v4-2/docs/api-v2-get-list-an-ldap-server).

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | object | O servidor LDAP atualizado. |
| `data.id` | integer | Código de identificação único do servidor. |
| `data.ldap_server` | object | Atributos do servidor, com todos os campos retornados. |
| `meta` | object | Metadados do recurso. |
| `meta.links.self` | string | Caminho do servidor. |
| `meta.actions` | object | Ações disponíveis para o servidor em seu estado atual. |

              Info

              

A partir da versão 4.2.10, a resposta retorna `id` e o `id` de cada objeto aninhado como string, por exemplo `"7"`. O corpo das requisições continua recebendo esses valores como inteiros.

---

## Erros

| Código HTTP | Mensagem | Causa possível | Solução |
| --- | --- | --- | --- |
| `400` | `api.request.bad_request` | A requisição carrega um parâmetro de query desconhecido. | Remova o parâmetro e reenvie a requisição. |
| `401` | `api.auth.unauthorized` | O token de acesso está ausente ou expirou. | Solicite um novo token de acesso. |
| `404` | `api.resource.not_found` | O servidor não existe. | Verifique o código de identificação enviado no caminho. |
| `409` | `api.resource.inactive` | O servidor está inativo, e um servidor inativo não pode ser alterado. | Ative o servidor com [POST \| Ativar servidor LDAP](/v4-2/docs/api-v2-post-activate-ldap-server) e reenvie a requisição. |
| `412` | `api.precondition.failed` | O valor de `If-Match` não corresponde à versão atual do servidor, o que significa que o servidor foi alterado depois de ser lido. | Leia o servidor novamente com [GET \| Listar um servidor LDAP por [id]](/v4-2/docs/api-v2-get-list-an-ldap-server), revise as alterações e reenvie a requisição com o novo `ETag`. |
| `422` | `api.validation.required_field` | Um campo obrigatório está ausente do corpo da requisição. | Adicione o campo ausente e reenvie a requisição. |
| `422` | `api.validation.order.duplicate` | Outro servidor ativo já usa este valor de `order`. | Envie um valor diferente ou desative o servidor que usa esse valor. |
| `422` | `api.validation.invalid_reference` | O domínio, a credencial ou o network connector referenciado não existe. | Verifique os códigos de identificação enviados no corpo. |
| `422` | `api.enum.invalid_value` | `account_form` ou `group_scope` recebeu um valor fora da lista permitida. | Verifique os valores permitidos para o campo e reenvie a requisição. |
| `422` | `patch.field.not.allowed` | O corpo carrega um campo somente leitura, como `active`, `account_domain_name` ou `account_domain_name_short`. | Remova o campo e reenvie a requisição. |
| `428` | `api.precondition.required` | A requisição chegou sem o cabeçalho `If-Match`. | Leia o servidor e reenvie a requisição com o valor do `ETag` em `If-Match`. |
| `429` | `api.rate_limit.exceeded` | O limite de requisições foi excedido. | Reduza a frequência de requisições e tente novamente. |

### Exemplo de resposta de erro

`428` a requisição chegou sem o cabeçalho `If-Match`:

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

Para mensagens de erros de autenticação e a política de `403` versus `404`, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).