POST | Create LDAP server

Description

Create an LDAP/AD server connection profile in the Segura™ platform. A single request defines the host and port, the PAM credential used for the bind, the base DN, the account format, the evaluation order in the authentication chain, and the group query parameters.

The server is created in the active state and joins the authentication chain immediately. It is the same record the web interface manages in Settings > Authentication > LDAP/AD, so a server created here appears there, and the reverse.

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.
A domain registered in the platform, to reference in domain_id.
A PAM credential holding the bind account, to reference in bind_credential_id.

Info

An access token carries only the authorizations that existed when it was generated. After the administrator enables the Users authorization, generate a new token for the application, an existing token will not gain the new authorization.

Request

POST /api/v2/iam/ldap-servers

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.

Request body

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. The lower value is evaluated first. 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. The credential must have a 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. Returns `null` when the server is reached directly.
`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.

Attention

bind_credential_id is required. The API binds to the directory through a PAM credential, and it does not accept a user name and password sent in the request body.

Three fields cannot be sent at all. The active state is changed through POST | Activate LDAP server and POST | Deactivate LDAP server, and account_domain_name and account_domain_name_short are derived from the domain referenced in domain_id. Sending any of the three returns 422 patch.field.not.allowed.

Example request

POST {{url}}/api/v2/iam/ldap-servers

Body

{
    "host": "ad.example.com",
    "port": 389,
    "dn_base": "CN=Users,DC=example,DC=com",
    "use_ssl": false,
    "member_is_dn": false,
    "bind_requires_dn": false,
    "account_form": "principal",
    "order": 1,
    "domain_id": 5,
    "bind_credential_id": 102,
    "use_credential_domain": false,
    "ignore_disabled_expired": false
}

Response

HTTP/1.1 201 Created
Location: /api/v2/iam/ldap-servers/7

The Location header holds the path of the created server.

Info

In version 4.2.7, the 201 response does not carry an ETag header. From version 4.2.10, it does, and you can use that value in If-Match directly. Send a GET | List an LDAP server by [id] request to the path in Location to read the server's current version, which PUT | Update LDAP server by [id] and PATCH | Partially update LDAP server by [id] require in the If-Match header.

Example response body

{
    "data": {
        "id": 7,
        "ldap_server": {
            "host": "ad.example.com",
            "port": 389,
            "dn_base": "CN=Users,DC=example,DC=com",
            "active": true,
            "use_ssl": false,
            "member_is_dn": false,
            "bind_requires_dn": false,
            "account_form": "principal",
            "order": 1,
            "domain": { "id": 5, "name": "EXAMPLE.COM" },
            "bind_credential": {
                "id": 102,
                "username": "[email protected]",
                "domain": { "id": 5, "name": "EXAMPLE.COM" }
            },
            "network_connector": null,
            "account_filter_format": null,
            "use_credential_domain": false,
            "ignore_disabled_expired": false,
            "username_attribute": null,
            "dn_bind": null,
            "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-08T22:42:34+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

Field	Type	Description
`data`	object	The created LDAP server.
`data.id`	integer	Unique identification code of the server, assigned by Segura™.
`data.ldap_server`	object	Attributes of the server.
`data.ldap_server.host`	string	Hostname or IP address of the directory server.
`data.ldap_server.port`	integer	Port the directory listens on.
`data.ldap_server.dn_base`	string	Base distinguished name for user searches.
`data.ldap_server.active`	boolean	Indicates whether the server is active. A created server is always active.
`data.ldap_server.use_ssl`	boolean	Indicates whether LDAPS is enabled.
`data.ldap_server.member_is_dn`	boolean	Indicates that the member attribute returns a full distinguished name.
`data.ldap_server.bind_requires_dn`	boolean	Indicates that the directory requires a distinguished name to bind.
`data.ldap_server.account_form`	string	Username format the directory expects.
`data.ldap_server.order`	integer	Evaluation order in the authentication chain.
`data.ldap_server.domain`	object	Domain the server belongs to. Returns `null` when the stored domain name matches no registered domain.
`data.ldap_server.domain.id`	integer	Identification code of the domain.
`data.ldap_server.domain.name`	string	Name of the domain.
`data.ldap_server.bind_credential`	object	PAM credential used for the bind.
`data.ldap_server.bind_credential.id`	integer	Identification code of the credential.
`data.ldap_server.bind_credential.username`	string	Username of the credential.
`data.ldap_server.bind_credential.domain`	object	Domain of the credential.
`data.ldap_server.network_connector`	object	Network connector agent used to reach the server. Returns `null` when the server is reached directly.
`data.ldap_server.network_connector.id`	integer	Identification code of the network connector agent.
`data.ldap_server.network_connector.name`	string	Name of the network connector agent.
`data.ldap_server.account_filter_format`	string	Custom LDAP filter used to locate an account.
`data.ldap_server.use_credential_domain`	boolean	Indicates whether the domain of the bind credential is used.
`data.ldap_server.ignore_disabled_expired`	boolean	Indicates whether expired accounts are skipped during group synchronization.
`data.ldap_server.username_attribute`	string	Directory attribute holding the username.
`data.ldap_server.dn_bind`	string	Base path used for the bind operation.
`data.ldap_server.account_domain_name`	string	Domain name applied to accounts. Derived from the referenced domain and read-only.
`data.ldap_server.account_domain_name_short`	string	Short domain name applied to accounts. Derived from the referenced domain and read-only.
`data.ldap_server.group`	string	Group whose members are allowed to authenticate.
`data.ldap_server.group_dn`	string	Base distinguished name for group searches.
`data.ldap_server.group_attribute`	string	Directory attribute holding the group name.
`data.ldap_server.group_scope`	string	Scope of the group search.
`data.ldap_server.group_filter`	string	LDAP filter applied when searching for groups.
`data.ldap_server.member_attribute`	string	Group attribute listing its members.
`data.ldap_server.created_at`	datetime	Date and time the server was created, in ISO 8601 format.
`data.ldap_server.updated_at`	datetime	Date and time the server was last changed, in ISO 8601 format.
`meta`	object	Resource metadata.
`meta.links`	object	Navigation links for the created resource.
`meta.links.self`	string	Path of the created server.
`meta.actions`	object	Actions available for the server in its current state. A server created as active offers `test-connection` and `deactivate`.

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.
`403`	`api.auth.forbidden`	The authorization does not have permission to manage LDAP servers.	Ask the administrator to check the Users authorization in A2A, then generate a new token.
`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.invalid_type`	A field received a value of the wrong type.	Check the type expected for the field and resend the request.
`422`	`api.validation.port.out_of_range`	`port` is outside the range `1` to `65535`.	Send a port inside the range.
`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 `domain_id`, `bind_credential_id`, and `network_connector_id`.
`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.
`429`	`api.rate_limit.exceeded`	The request rate limit was exceeded.	Reduce the request rate and try again.

Example error response

422 another active server already uses the order value:

{
    "code": "api.validation.order.duplicate",
    "message": "Another active LDAP server already uses this order.",
    "details": [
        { "field": "order", "code": "api.validation.order.duplicate" }
    ]
}

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