GET | List all LDAP servers

Description

List the LDAP/AD server connection profiles registered in the Segura™ platform. The response is paginated and supports field projection, filters, and sorting.

This endpoint returns a summary of each server. To read every attribute of one server, access GET | List an LDAP server by [id].

Prerequisites

An application with the Users authorization granted by the administrator in A2A. 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

GET /api/v2/iam/ldap-servers

Query parameters

Field	Type	Required	Description
`page`	integer	No	Page to return. Default: `1`.
`limit`	integer	No	Number of servers per page. Default: `50`. Maximum: `200`.
`sort_by`	string	No	Comma-separated list of fields and directions. See Sorting.
`fields`	string	No	Comma-separated list of fields to return. Allowed values: `id`, `host`, `port`, `active`, `use_ssl`, `order`, `domain`.
`search`	string	No	Free-text search across `host`, `dn_base`, and `account_domain_name`.
`ldap_server.host`	string	No	Returns the servers with this host.
`ldap_server.port`	integer	No	Returns the servers on this port.
`ldap_server.active`	boolean	No	Returns the active or the inactive servers.
`ldap_server.use_ssl`	boolean	No	Returns the servers with LDAPS enabled or disabled.
`ldap_server.domain_id`	integer	No	Returns the servers of this domain.
`ldap_server.bind_credential_id`	integer	No	Returns the servers that bind with this PAM credential.
`ldap_server.network_connector_id`	integer	No	Returns the servers reached through this network connector agent.

Attention

Filter and sort fields carry the ldap_server. prefix. The short forms, such as ?active=true or ?sort_by=host:asc, are not part of the contract: a short filter name returns 400 api.request.bad_request and a short sort field returns 422.

Filter operators

ldap_server.host also accepts a suffix that changes how the value is matched. Without a suffix, the match is exact.

Suffix	Example	Description
`_contains`	`?ldap_server.host_contains=example`	The host contains the value.
`_starts_with`	`?ldap_server.host_starts_with=ad.`	The host starts with the value.
`_ends_with`	`?ldap_server.host_ends_with=.com`	The host ends with the value.

Sorting

sort_by takes a comma-separated list of segments, each one a field and a direction separated by a colon, such as ldap_server.order:asc. The direction is either asc or desc.

Sortable fields: id, ldap_server.host, ldap_server.port, ldap_server.active, ldap_server.use_ssl, ldap_server.order, ldap_server.created_at, ldap_server.updated_at.

Example request

GET {{url}}/api/v2/iam/ldap-servers?ldap_server.active=true&sort_by=ldap_server.order:asc&page=1&limit=50

Response

HTTP/1.1 200 OK

Example response body

{
    "data": [
        {
            "id": 7,
            "host": "ad.example.com",
            "port": 389,
            "active": true,
            "use_ssl": false,
            "order": 1,
            "domain": { "id": 5, "name": "EXAMPLE.COM" }
        },
        {
            "id": 9,
            "host": "ad.private.example.com",
            "port": 636,
            "active": true,
            "use_ssl": true,
            "order": 2,
            "domain": null
        }
    ],
    "meta": {
        "pagination": { "page": 1, "limit": 50, "total_items": 2, "total_pages": 1 },
        "links": {
            "self": "/api/v2/iam/ldap-servers?ldap_server.active=true&sort_by=ldap_server.order:asc&page=1&limit=50"
        }
    }
}

Response body fields

Field	Type	Description
`data`	array of objects	Servers matching the request.
`data[].id`	integer	Unique identification code of the server, assigned by Segura™.
`data[].host`	string	Hostname or IP address of the directory server.
`data[].port`	integer	Port the directory listens on.
`data[].active`	boolean	Indicates whether the server is active.
`data[].use_ssl`	boolean	Indicates whether LDAPS is enabled.
`data[].order`	integer	Evaluation order in the authentication chain.
`data[].domain`	object	Domain the server belongs to. Returns `null` when the stored domain name matches no registered domain.
`data[].domain.id`	integer	Identification code of the domain.
`data[].domain.name`	string	Name of the domain.
`meta`	object	Response metadata.
`meta.pagination`	object	Pagination state of the response.
`meta.pagination.page`	integer	Page returned.
`meta.pagination.limit`	integer	Number of servers per page.
`meta.pagination.total_items`	integer	Total number of servers matching the request.
`meta.pagination.total_pages`	integer	Total number of pages.
`meta.links`	object	Navigation links for the listing.
`meta.links.self`	string	Path of the request.

Info

The listing returns a summary of each server, with the fields flat inside each item. The detail endpoint returns every attribute, nested under ldap_server. Access GET | List an LDAP server by [id] for the full shape.

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, such as a filter without the `ldap_server.` prefix.	Check the parameter name and resend the request.
`401`	`api.auth.unauthorized`	The access token is missing or has expired.	Request a new access token.
`422`	`api.sort.invalid_field`	`sort_by` names a field that is not sortable.	Send one of the fields named in the Sorting section.
`422`	`api.sort.invalid_direction`	A `sort_by` segment carries a direction other than `asc` or `desc`.	Correct the direction and resend the request.
`429`	`api.rate_limit.exceeded`	The request rate limit was exceeded.	Reduce the request rate and try again.

For authentication error messages and the 403 versus 404 policy, access API v2 - Conventions and shared behaviors.