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

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.
A valid OAuth 2.0 access token. For more information, access 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.

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