Save the directory configuration.

PUT

/api/v1/settings/ldap

curl --request PUT \
  --url https://example.com/api/v1/settings/ldap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "bind_dn": "example", "bind_password": "example", "ca_cert": "example", "default_role": "example", "enabled": true, "group_base_dn": "example", "group_filter": "example", "group_name_attribute": "example", "host": "example", "member_of_attribute": "example", "port": 1, "role_map": { "additionalProperty": "example" }, "security": "ldaps", "uid_attribute": "example", "user_base_dn": "example", "user_filter": "example", "username_attribute": "example" }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

The save payload from the Settings page.

object

bind_dn

required

string

bind_password

Write-only credential. Two-valued, not three: None keeps what is stored, a non-blank value replaces it. An empty string is a validation error rather than “clear”, because a bind with a DN and no password is an unauthenticated bind that a permissive directory answers success — so “no password” is not a configuration, it is a silent downgrade to anonymous.

string | null

ca_cert

string | null

default_role

string | null

enabled

boolean

group_base_dn

string | null

group_filter

string | null

group_name_attribute

string

host

required

string

member_of_attribute

string

port

integer format: int32

role_map

object

key

additional properties

string

security

How the connection is protected. Two variants, both TLS — there is deliberately no plaintext option, so ldap:// cannot be configured into existence and the bind password cannot cross the wire in the clear. Adding one later would be a certificate-verification-disable flag by another name and needs the same argument (ADR-041 decision 2).

string

Allowed values: ldaps starttls

uid_attribute

string

user_base_dn

required

string

user_filter

string

username_attribute

string

Responses

204

Saved

400

The configuration is not usable; the message names the field

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks the user-administration permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

This deployment has no directory store

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}