Exercise the **saved** configuration against the directory.
const url = 'https://example.com/api/v1/settings/ldap/test';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"username":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/settings/ldap/test \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "username": "example" }'Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Which account, if any, the test should look up.
object
A username to resolve. Optional: with none, the check still proves the connection, the TLS trust and the service account’s bind. With one, it also reports the DN, the groups and the role that user would receive — without binding as them, so it can neither be used as a credential-testing proxy into the directory nor push anybody towards their domain’s lockout threshold.
Examplegenerated
{ "username": "example"}Responses
Section titled “Responses”How far the check got; a failed stage is reported here, not as an error status
The Test button’s result.
Staged rather than a single boolean on purpose. This probe cannot prove that logging in works,
because it deliberately never binds as the user (see [probe]) — so an ok: true alone would
be read as “login works” when the directory may still refuse simple binds, or the account may be
disabled. Naming the stages says exactly how far it got.
object
What this probe did not test, so a green result is not over-read.
Every stage passed.
The role this user would receive. None means they would be denied — the commonest
misconfiguration, and one the login form reports as an indistinguishable wrong password.
One step of the Test button’s report.
object
Why it failed, or what it found. Truncated — this is remote-influenced text.
connect | bind_service | search_user | resolve_groups.
Whether the entry carried the configured id attribute — the flag, not the value. Its absence is the failure this field exists to surface, and the value itself is of no use here.
Examplegenerated
{ "groups": [ "example" ], "groups_truncated": true, "note": "example", "ok": true, "role": "example", "stages": [ { "detail": "example", "name": "example", "ok": true } ], "subject_present": true, "user_dn": "example", "username_resolved": "example"}No directory configuration has been saved yet
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}No valid bearer token
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Role lacks the user-administration permission
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}This deployment has no directory store
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}