Probe the directory (admin-only, read-only)
const url = 'https://example.com/api/admin/ldap/probe';const options = { method: 'POST', headers: { 'X-Ssoossh-Key-Secret': '<X-Ssoossh-Key-Secret>', 'Content-Type': 'application/json' }, body: '{}'};
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/admin/ldap/probe \ --header 'Content-Type: application/json' \ --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>' \ --data '{}'Runs one directory lookup through the login path’s three stages — lookup, field resolution, then the merge and allowlist — and stops before the write. Reports the filter it actually sent, every attribute the directory returned rather than the ones the configuration names, what each field resolved to, which group values the allowlist would drop, and the config lines that would keep what is currently ignored.
The connection is not part of the request: the probe always uses the running ldap.url, bind credentials and base_dn, so it cannot be pointed at another host. It writes nothing.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”What to ask the directory
object
What to ask the directory
object
Attributes are the attribute names to request. Empty requests every user attribute, which is the point of the console.
BindingSource selects where the template bindings come from: “self” (the calling admin’s own identity, the default), “user” (an existing user named by UserID), or “custom” (the typed Bindings below).
Bindings are the typed values used when BindingSource is “custom”.
object
object
Filter is the filter to run. Empty in template mode means the configured ldap.user_filter.
Mode is “template” (render Filter against the bindings, with RFC 4515 escaping applied) or “literal” (send Filter exactly as typed). Defaults to template.
UserID names the user to bind against when BindingSource is “user”.
Example generated
{}Responses
Section titled “Responses”What the probe found
object
BaseDN, FilterSent, Mode and Attributes are the request as it went out, so an operator sees the rendered filter rather than the template.
object
object
Configured reports that a configured field reads this attribute, which is what the console highlights.
TruncatedValues is how many values the probe’s own cap dropped.
object
Attribute is the entry attribute the field reads, absent for a search-only field.
AttributePresent distinguishes an attribute that is empty from one that is not on the entry at all — which is usually a typo.
object
BaseDN and FilterSent are what actually went to the directory.
Value is the attribute read off each matched entry.
Values is what the field resolved to, as the login path would compute it.
IDAttribute echoes ldap.id_attribute and DirectoryID is what it resolved to on the matched entry — the value that would be stored as the re-anchoring identifier. Both empty when it is unconfigured, in which case Suggestions names a candidate the entry actually carries.
Matched is how many entries the filter found, counted up to the probe’s limit. The login path refuses anything but exactly one.
MatchedCapped reports that the count stopped at a size limit, the probe’s or the directory’s, so Matched is a floor.
MatchedDNs lists the matching entries’ DNs when more than one matched, capped by the probe; Matched minus its length is how many were left out. Absent when one entry or none matched.
object
Action is “override”, “persist-groups” or “extra”.
Kept and Dropped split the values by the group allowlist. Dropped is only ever non-empty for the group field.
object
TLSInsecureSkipVerify reports that the connection did not verify the directory certificate.
Wrote is always false and is serialized anyway: the guarantee is part of the response, not only of the documentation.
Example generated
{ "attributes": [ "example" ], "base_dn": "example", "directory_id": "example", "elapsed_ms": 1, "entry": { "attributes": [ { "configured": true, "name": "example", "truncated_values": 1, "values": [ "example" ] } ], "dn": "example" }, "fields": [ { "attribute": "example", "attribute_present": true, "attribute_values": [ "example" ], "error": "example", "name": "example", "searches": [ { "base_dn": "example", "entries": 1, "error": "example", "filter_sent": "example", "name": "example", "value": "example", "values": [ "example" ] } ], "values": [ "example" ] } ], "filter_sent": "example", "id_attribute": "example", "matched": 1, "matched_capped": true, "matched_dns": [ "example" ], "merge": [ { "action": "example", "dropped": [ "example" ], "kept": [ "example" ], "name": "example", "note": "example" } ], "mode": "example", "suggestions": [ { "reason": "example", "yaml": "example" } ], "timeout_ms": 1, "tls_insecure_skip_verify": true, "wrote": true}Invalid request, filter or bindings
object
Data is always null on an error response.
Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.
ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.
Example
{ "error": "certificate request \"9f1c…\" not found", "error_code": "not_found"}Not authenticated
object
Data is always null on an error response.
Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.
ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.
Example
{ "error": "certificate request \"9f1c…\" not found", "error_code": "not_found"}Not authorized as admin
object
Data is always null on an error response.
Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.
ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.
Example
{ "error": "certificate request \"9f1c…\" not found", "error_code": "not_found"}The user to bind against does not exist
object
Data is always null on an error response.
Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.
ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.
Example
{ "error": "certificate request \"9f1c…\" not found", "error_code": "not_found"}Too many probes
object
Data is always null on an error response.
Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.
ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.
Example
{ "error": "certificate request \"9f1c…\" not found", "error_code": "not_found"}