---
title: "POST | Test LDAP server connection by [id]"
slug: "api-v2-post-test-ldap-server-connection"
updated: 2026-11-03T14:57:57Z
published: 2026-11-03T14:57:57Z
canonical: "docs.senhasegura.io/api-v2-post-test-ldap-server-connection"
---

> ## 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 | Test LDAP server connection by [id]

## Description

Start a connection test against an LDAP/AD server registered in the Segura™ platform. The test performs a real bind with the server's PAM credential and then a search on its base distinguished name.

The test always runs in the background. The request returns `202 Accepted` with a job descriptor, and the result is read through [GET | List an IAM job by [id]](/v4-2/docs/api-v2-get-list-an-iam-job).

---

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

---

## Request

`POST` `/api/v2/iam/ldap-servers/{id}/test-connection`

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

The request takes no body.

              Info

              

The test runs on inactive servers too, so a connection can be checked before the server is put back in the authentication chain.

---

### Example request

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

---

## Response

```
HTTP/1.1 202 Accepted
Location: /api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8
```

The `Location` header holds the path of the job created for this test.

### Example response body

```
{
    "data": {
        "job": {
            "id": "019e0a01-b7b8-7062-82dd-43a8aa0ed6f8",
            "type": "ldap.test_connection",
            "state": "queued",
            "retry_count": 0,
            "created_at": "2026-05-08 23:52:25",
            "started_at": null,
            "finished_at": null
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-servers/7/test-connection" }
    }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The accepted request. |
| `data.job` | object | Job created for the test. |
| `data.job.id` | string | Unique identification code of the job, in UUID format. Use it to read the result. |
| `data.job.type` | string | Type of job. Returns `ldap.test_connection`. |
| `data.job.state` | string | State of the job. A newly accepted test returns `queued`. |
| `data.job.retry_count` | integer | Number of times the job was retried. |
| `data.job.created_at` | datetime | Date and time the job was created. |
| `data.job.started_at` | datetime | Date and time a worker picked the job up. Returns `null` until then. |
| `data.job.finished_at` | datetime | Date and time the job ended. Returns `null` until then. |
| `meta` | object | Response metadata. |
| `meta.links` | object | Navigation links for the request. |
| `meta.links.self` | string | Path of the test-connection action. |

---

## Reading the result

Send a [GET | List an IAM job by [id]](/v4-2/docs/api-v2-get-list-an-iam-job) request to the path in `Location` until `state` is `succeeded` or `failed`.

A successful test returns a `result` object:

| Field | Type | Description |
| --- | --- | --- |
| `bind_ok` | boolean | Indicates whether the bind succeeded. |
| `base_search_ok` | boolean | Indicates whether the search on the base distinguished name succeeded. |
| `elapsed_ms` | integer | Time the test took, in milliseconds. |
| `translated_host` | string | Host the platform reached. |
| `translated_port` | integer | Port the platform reached. |

A failed test returns an `error` object whose `code` is one of the following.

| Code | Description |
| --- | --- |
| `api.ldap.test_connection.server_not_found` | The server record was removed while the job was queued. |
| `api.ldap.test_connection.no_credential` | The server has no PAM credential to bind with. |
| `api.ldap.test_connection.credential_decrypt_failed` | The bind credential could not be decrypted. |
| `api.ldap.test_connection.vault_unavailable` | The vault did not answer in time. |
| `api.ldap.test_connection.network_connector_unsupported` | The server is reached through a network connector agent, which this version cannot test. |
| `api.ldap.test_connection.dc_unavailable` | The directory server did not answer. |
| `api.ldap.test_connection.bind_failed` | The bind failed for a reason other than an unreachable directory, for example a rejected credential, a TLS error, or a timeout. |
| `api.ldap.test_connection.search_failed` | The bind succeeded, but the search on the base distinguished name failed. |

              Attention

              

A server that reaches the directory through a network connector agent, which is a server with `network_connector_id` set, cannot be tested in this version. The job fails with `api.ldap.test_connection.network_connector_unsupported`. Every other operation on the server works as usual.

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `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. |
| `429` | `api.rate_limit.exceeded` | The request rate limit was exceeded. | Reduce the request rate and try again. |

The platform also answers `503 Service Unavailable` (`api.service.unavailable`) when the background worker queue is full and the test cannot be queued. The response body carries the number of seconds to wait before resending the request in `details.retry_after`. From version 4.2.15, the platform also sends the same value in the `Retry-After` header.

              Info

              

A `202` response means the test was queued, not that the connection works. Read the job to learn the outcome.

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