This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

Management API

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/ldap

getLdapSettings

The embedded directory’s own settings

The six ldap.* settings: the two raw ports, the base DN, whether a name seen for the first time gets an entry, and the two ceilings that keep it from being filled up.

NOTHING HERE REFUSES A BIND, and no setting is missing: the MODE decides. In development any DN with any password, and anonymous, are accepted on 389 and 636 alike; in product only a person binds, on 636, with a password verified against their entry. There is no such behaviour to turn on.

The base DN is the DEFAULT realm’s directory and every other realm is a subtree beneath it, because a socket has no path to put a realm segment in and a DN is the one name a client can carry. What is IN the directory is GET /users and GET /groups.

THERE IS NO POST BESIDE THIS ONE and that is not a gap: every form on the console page this mirrors posts set-many to /admin/config, so POST /admin-api/config/set-many is already the operation for it. One store, one action, two doors.

Mirrors GET /admin/ldap on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: What the page says, and the settings it draws — described rows carrying each value’s source and whether it can be changed while the service runs.

Member Type Required What it is
alsoHtml list    
alsoHtml[] string    
leadHtml string    
links list    
links[].href string    
links[].what string    
notes list    
notes[] string    
page string    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
settings object    
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string, or null    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string, or null    
settings.editableCount integer    
settings.groups list    
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   The sentence beside each value.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list    
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or boolean, or number, or string, or null    
settings.groups[].settings[].default[] string    
settings.groups[].settings[].description string    
settings.groups[].settings[].editRefusal string    
settings.groups[].settings[].editable boolean    
settings.groups[].settings[].enumValues list    
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string, or null    
settings.groups[].settings[].group string    
settings.groups[].settings[].key string    
settings.groups[].settings[].label string    
settings.groups[].settings[].legacyEnv string, or null    
settings.groups[].settings[].masked boolean    
settings.groups[].settings[].max number    
settings.groups[].settings[].min number    
settings.groups[].settings[].ordered boolean    
settings.groups[].settings[].overridden boolean    
settings.groups[].settings[].realmSettable boolean    
settings.groups[].settings[].restartReason string    
settings.groups[].settings[].selectAll map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings.groups[].settings[].selectAll.{key} list    
settings.groups[].settings[].selectAll.{key}[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source string    
settings.groups[].settings[].step number    
settings.groups[].settings[].text string, or null    
settings.groups[].settings[].type string    
settings.groups[].settings[].value list, or boolean, or number, or string, or null    
settings.groups[].settings[].value[] string    
settings.overridden list    
settings.overridden[] string    
settings.page string    
settings.setWith string    
settings.settingCount integer    
settings.sharedWith map   The other pages, by settings group.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string    
settings.sharedWith.{key}[].path string    
title string    
what string    

GET /admin-api/ldap/applications

getDirectoryApplications

The application registry as the directory holds it, and its schema

One entry per identifier under ou=applications, every attribute on it, and the published SCHEMA — the object classes and every attribute name with what sets it.

THE SCHEMA IS WHY THIS IS NOT GET /admin-api/applications. That operation is the registry as the console works with it: the counters, the drill-down, the writes. This is the registry as the DIRECTORY holds it, and the vocabulary is the half a client reading an entry back over 389 actually needs — this directory is schemaless, so an entry carrying thirty invented attribute names is otherwise guesswork.

THESE ENTRIES ARE THE REGISTRY rather than a copy of one. Nothing caches them, so an ldapmodify of oauthRedirectUri changes which redirect URI RFC 9700 mode accepts on the next request.

Two attributes hold CREDENTIALS in the clear, for the reason the development Kerberos passwords are printed as settings. They are never written to the audit log.

Mirrors GET /admin/ldap/applications on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of the identifier, the name, the DN or any attribute value. Case-insensitive.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The page of entries, the kinds and the schema.

Member Type Required What it is
applications list    
applications[].allowedProtocols list    
applications[].allowedProtocols[] string    
applications[].attributes map   Attribute names, which are data in a schemaless directory, and values.
applications[].attributes.{key} list, or string, or null    
applications[].attributes.{key}[] string    
applications[].authentications number    
applications[].createdAt string, or null    
applications[].declaredKinds list    
applications[].declaredKinds[] string    
applications[].description string, or null    
applications[].dn string, or null    
applications[].dnLabel string, or null    
applications[].fields map   Attribute names, which are data in a schemaless directory, and values.
applications[].fields.{key} list, or string, or null    
applications[].fields.{key}[] string    
applications[].firstSeen string    
applications[].identifier string    
applications[].kinds list    
applications[].kinds[] string    
applications[].lastSeen string    
applications[].modifiedAt string, or null    
applications[].name string, or null    
applications[].operational list    
applications[].operational[] string    
applications[].origin string, or null    
applications[].protocols list    
applications[].protocols[] string    
applications[].recordedProtocols list    
applications[].recordedProtocols[] string    
applications[].registered boolean    
applications[].registeredBy string    
applications[].returnAddressesObserved list    
applications[].returnAddressesObserved[].attribute string    
applications[].returnAddressesObserved[].held boolean    
applications[].returnAddressesObserved[].trusted boolean    
applications[].returnAddressesObserved[].value string    
applications[].sessions number    
applications[].users number    
baseDn string    
container string    
count integer    
directory boolean    
filter object    
filter.q string, or null    
firstRow integer    
kinds list    
kinds[].kind string    
kinds[].label string    
kinds[].what string    
lastRow integer    
matched integer    
max integer    
message string    
page integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
perPage integer    
schema object    
schema.attributes list    
schema.attributes[].editable boolean, or string    
schema.attributes[].enum list    
schema.attributes[].enum[] string    
schema.attributes[].families list    
schema.attributes[].families[] string    
schema.attributes[].familyWhy string    
schema.attributes[].from string    
schema.attributes[].identifier boolean    
schema.attributes[].identifierName string    
schema.attributes[].kind string    
schema.attributes[].name string    
schema.attributes[].overrides string    
schema.attributes[].role string    
schema.attributes[].secret boolean    
schema.attributes[].sensitive boolean    
schema.attributes[].standard boolean    
schema.attributes[].strictOverride boolean    
schema.attributes[].what string    
schema.objectClasses list    
schema.objectClasses[].name string    
schema.objectClasses[].standard boolean    
schema.objectClasses[].what string    
schema.objectClasses[].where string    
shown integer    
sourceOfTruth string    

GET /admin-api/ldap/devices

getDirectoryDevices

The device register as the directory holds it, and its schema

One entry per device under ou=devices, every attribute on it, and the SCHEMA common/devices.ts publishes. A key, the last compliance and status change and the enrolment are ONE JSON VALUE each. stsDeviceSecretHash is withheld, as from every LDAP read; every other value is shown as the directory holds it. Read-only: the register is edited through /admin-api/devices.

WHERE THE DIRECTORY IS A WINDOW (#359) the count and the page are asked of the store, and a q looks inside at most a bounded number of entries and says so in search. A page past the walk’s cap (100,000 entries) is empty and carries pageCap.

Mirrors GET /admin/ldap/devices on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of the DN or of any value but the withheld one.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The page of device entries and the schema.

Member Type Required What it is
baseDn string    
container string    
count integer    
directory boolean    
entries list    
entries[].attributes map   Attribute names, which are data in a schemaless directory, and values.
entries[].attributes.{key} list, or string, or null    
entries[].attributes.{key}[] string    
entries[].dn string    
filter object    
filter.q string, or null    
firstRow integer    
lastRow integer    
matched integer    
message string    
page integer    
pageCap integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
perPage integer    
schema object    
schema.attributes list    
schema.attributes[].editable boolean, or string    
schema.attributes[].enum list    
schema.attributes[].enum[] string    
schema.attributes[].families list    
schema.attributes[].families[] string    
schema.attributes[].familyWhy string    
schema.attributes[].from string    
schema.attributes[].identifier boolean    
schema.attributes[].identifierName string    
schema.attributes[].kind string    
schema.attributes[].name string    
schema.attributes[].overrides string    
schema.attributes[].role string    
schema.attributes[].secret boolean    
schema.attributes[].sensitive boolean    
schema.attributes[].standard boolean    
schema.attributes[].strictOverride boolean    
schema.attributes[].what string    
schema.objectClasses list    
schema.objectClasses[].name string    
schema.objectClasses[].standard boolean    
schema.objectClasses[].what string    
schema.objectClasses[].where string    
search object    
search.complete boolean    
search.scanLimit integer    
search.scanned integer    
shown integer    
sourceOfTruth string    

GET /admin-api/ldap/directory

getDirectoryEntries

Every entry in this realm’s directory, paged

The whole store, DN by DN, with where each entry came from — seed, an LDAP add, or an authentication — and every attribute with every value.

IT IS NOT AN LDAP SEARCH. This is the service showing its own store, which is how a caller tells an empty directory from a filter that matched nothing, and it is why the operational attributes are here: a search withholds createTimestamp and modifyTimestamp unless they are asked for by name (RFC 4511 §4.5.1.8) and this is not a search.

q matches the DN, any attribute NAME and any attribute VALUE, case-insensitively — values because the caller who needs this most often has a thumbprint or a secret in hand and no idea which entry carries it.

WHERE THE DIRECTORY IS HELD AS A WINDOW ONTO THE STORE (#616) the counts, the origin filter, the order and the page are asked of the store, so the order is the store’s key order (order: key), and a q — which matches values the store holds sealed — looks inside at most a bounded number of entries and says how many in search.

THE REPLY IS THIS REALM’S DIRECTORY AND NO OTHER. Since 2026-08-25 each trust realm has a subtree of its own; reach another realm’s through its own path prefix.

Mirrors GET /admin/ldap/directory on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of the DN, of an attribute name, or of an attribute value. Case-insensitive.
origin query string   Only entries that came from here. The values actually present are in origins.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The page of entries, with the filter and the paging.

Member Type Required What it is
baseDn string    
count integer    
directory boolean    
entries list    
entries[].attributes map   Attribute names, which are data in a schemaless directory, and values.
entries[].attributes.{key} list, or string, or null    
entries[].attributes.{key}[] string    
entries[].dn string    
entries[].origin string    
filter object    
filter.origin string, or null    
filter.q string, or null    
firstRow integer    
lastRow integer    
matched integer    
message string    
order string    
originCounts map   A count per name.
originCounts.{key} number    
origins list    
origins[] string    
page integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
perPage integer    
search object    
search.complete boolean    
search.scanLimit integer    
search.scanned integer    
shown integer    

GET /admin-api/ldap/federations

getDirectoryFederations

The federation register as the directory holds it, and its schema

The application registry’s twin, for ou=federations — and THE ONE CONTAINER IN THIS DIRECTORY WHERE AN LDAPMODIFY IS A SECURITY CHANGE. Everywhere else an edit changes what this service HANDS OUT; fedSigningCertificate decides whose assertions it will BELIEVE and fedEnabled turns a partner on.

It is a container of its own rather than a corner of ou=applications because half its entries are FOREIGN IDENTITY PROVIDERS, which ask this service for nothing at all.

The schema carries a column the applications one has no need of: which DIRECTION each attribute is for.

fedClientSecret is REDACTED in relationships and present in the entry’s own attributes, which is the same split the page makes: what a script reads is redacted, and a page claiming to say what the directory holds may not hide a value an ldapsearch shows.

Mirrors GET /admin/ldap/federations on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of the relationship id, the DN, the protocol or the direction. Case-insensitive.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The page of relationships, the roles, the protocols and the schema.

Member Type Required What it is
baseDn string    
container string    
count integer    
directory boolean    
enabledCount integer    
filter object    
filter.q string, or null    
firstRow integer    
lastRow integer    
matched integer    
max integer    
message string    
page integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
perPage integer    
protocols list    
protocols[].family string    
protocols[].label string    
protocols[].needs list    
protocols[].needs[] string    
protocols[].protocol string    
protocols[].signalsOnly boolean    
protocols[].spec string    
protocols[].what string    
relationships list    
relationships[].cn string    
relationships[].createdAt string    
relationships[].description list    
relationships[].description[] string    
relationships[].dn string    
relationships[].enabled boolean    
relationships[].entryAttributes map   Attribute names, which are data in a schemaless directory, and values.
relationships[].entryAttributes.{key} list, or string, or null    
relationships[].entryAttributes.{key}[] string    
relationships[].fedAcceptSignout string    
relationships[].fedAllowUnencrypted string    
relationships[].fedAllowUnsolicited string    
relationships[].fedAllowedTenants list    
relationships[].fedAllowedTenants[] string    
relationships[].fedApplication string    
relationships[].fedApplicationUse list    
relationships[].fedApplicationUse[] string    
relationships[].fedAttributeMap list    
relationships[].fedAttributeMap[] string    
relationships[].fedAuthentications string    
relationships[].fedAuthnMechanism string    
relationships[].fedAuthnRelationship string    
relationships[].fedAuthorizeParams list    
relationships[].fedAuthorizeParams[] string    
relationships[].fedAutocreateUsers string    
relationships[].fedBinding string    
relationships[].fedClientId string    
relationships[].fedClientSecret string    
relationships[].fedClientSigningKey string    
relationships[].fedContentEncryptionAlgorithm string    
relationships[].fedDiscovery string    
relationships[].fedEmailsUrl string    
relationships[].fedEnabled string    
relationships[].fedEncryptionKey list    
relationships[].fedEncryptionKey[] string    
relationships[].fedEncryptionKeyType string    
relationships[].fedEndSessionUrl string    
relationships[].fedFirstSeen string    
relationships[].fedHomeRealmDomain list    
relationships[].fedHomeRealmDomain[] string    
relationships[].fedId string    
relationships[].fedIdTokenSignedResponseAlg string    
relationships[].fedInitiateLogin string    
relationships[].fedJwks string    
relationships[].fedJwksUri string    
relationships[].fedKeyId string    
relationships[].fedKeyManagementAlgorithm string    
relationships[].fedLastError string    
relationships[].fedLastErrorAt string    
relationships[].fedLastSeen string    
relationships[].fedLastUser string    
relationships[].fedLocalEntityId string    
relationships[].fedMayAssertAdministrators string    
relationships[].fedName string    
relationships[].fedPeer string    
relationships[].fedProtocol string    
relationships[].fedProvider string    
relationships[].fedProvisionCap string    
relationships[].fedProvisionGroups string    
relationships[].fedProvisionIdleMinutes string    
relationships[].fedRefreshEverySeconds string    
relationships[].fedRefreshTokens string    
relationships[].fedRegister string    
relationships[].fedRegisteredIssuer string    
relationships[].fedRelease list    
relationships[].fedRelease[] string    
relationships[].fedRequestObject string    
relationships[].fedRequestObjectSigningAlg string    
relationships[].fedRequireSignedLogout string    
relationships[].fedResponseMode string    
relationships[].fedResponseType string    
relationships[].fedRole string    
relationships[].fedScope string    
relationships[].fedSignRequest string    
relationships[].fedSignalEmailMatch string    
relationships[].fedSignalsBearer string    
relationships[].fedSignalsClientId string    
relationships[].fedSignalsClientSecret string    
relationships[].fedSignalsDelivery string    
relationships[].fedSignalsEnabled string    
relationships[].fedSignalsEvents list    
relationships[].fedSignalsEvents[] string    
relationships[].fedSignalsIssuer string    
relationships[].fedSignalsScope string    
relationships[].fedSignalsTokenUrl string    
relationships[].fedSigningCertificate string    
relationships[].fedSloBinding string    
relationships[].fedSloUrl string    
relationships[].fedSsoUrl string    
relationships[].fedSubjectClaim string    
relationships[].fedSubjectDomain list    
relationships[].fedSubjectDomain[] string    
relationships[].fedSubjectGroup list    
relationships[].fedSubjectGroup[] string    
relationships[].fedSubjectPattern string    
relationships[].fedSubjectPolicy string    
relationships[].fedTeamId string    
relationships[].fedTokenAuth string    
relationships[].fedTokenUrl string    
relationships[].fedTrustAnchor string    
relationships[].fedUpdateUserAttributes string    
relationships[].fedUserinfoSignedResponseAlg string    
relationships[].fedUserinfoUrl string    
relationships[].fedUsernameSource string    
relationships[].fedUsers string    
relationships[].fedWebFinger string    
relationships[].missing list    
relationships[].missing[] string    
relationships[].modifiedAt string    
relationships[].protocolLabel string    
relationships[].ready boolean    
relationships[].roleShort string    
roles list    
roles[].label string    
roles[].role string    
roles[].short string    
roles[].what string    
schema object    
schema.attributes list    
schema.attributes[].editable boolean, or string    
schema.attributes[].enum list    
schema.attributes[].enum[] string    
schema.attributes[].families list    
schema.attributes[].families[] string    
schema.attributes[].familyWhy string    
schema.attributes[].from string    
schema.attributes[].identifier boolean    
schema.attributes[].identifierName string    
schema.attributes[].kind string    
schema.attributes[].name string    
schema.attributes[].overrides string    
schema.attributes[].role string    
schema.attributes[].secret boolean    
schema.attributes[].sensitive boolean    
schema.attributes[].standard boolean    
schema.attributes[].strictOverride boolean    
schema.attributes[].what string    
schema.objectClasses list    
schema.objectClasses[].name string    
schema.objectClasses[].standard boolean    
schema.objectClasses[].what string    
schema.objectClasses[].where string    
shown integer    
sourceOfTruth string    

GET /admin-api/ldap/peps

getDirectoryPeps

The registered remote PEPs as the directory holds them, and their schema

ALMOST EVERYTHING IN THIS CONTAINER IS A RECORD rather than configuration, which is what it has in common with ou=agents next door. A PEP registers itself, and its identity is taken from the CLIENT CERTIFICATE it presented and never from the body it sent.

Two attributes are not a record and an ldapmodify of either is a real change: xacmlPepEnabled is an administrator’s decision and a PEP that reconnects does not clear it, and xacmlPepNotifyUrl is one of the three addresses this service will dial.

AN EMPTY peps ARRAY IS NOT A FEATURE THAT IS OFF. A remote PEP pulls GET /xacml/pep/policies and converges without registering at all; registering is what buys it the change nudge and a row on the console.

Mirrors GET /admin/ldap/peps on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of a PEP name, a DN, or any value on the entry — a certificate subject or a notify URL included.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The page of registered PEPs and the schema.

Member Type Required What it is
baseDn string    
container string    
count integer    
directory boolean    
enabledCount integer    
filter object    
filter.q string, or null    
firstRow integer    
lastRow integer    
matched integer    
max integer    
message string    
page integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
peps list    
peps[].attributes map   Attribute names, which are data in a schemaless directory, and values.
peps[].attributes.{key} list, or string, or null    
peps[].attributes.{key}[] string    
peps[].createdAt string, or null    
peps[].dn string    
peps[].modifiedAt string, or null    
peps[].name string    
peps[].operational list    
peps[].operational[] string    
peps[].origin string, or null    
perPage integer    
schema object    
schema.attributes list    
schema.attributes[].editable boolean, or string    
schema.attributes[].enum list    
schema.attributes[].enum[] string    
schema.attributes[].families list    
schema.attributes[].families[] string    
schema.attributes[].familyWhy string    
schema.attributes[].from string    
schema.attributes[].identifier boolean    
schema.attributes[].identifierName string    
schema.attributes[].kind string    
schema.attributes[].name string    
schema.attributes[].overrides string    
schema.attributes[].role string    
schema.attributes[].secret boolean    
schema.attributes[].sensitive boolean    
schema.attributes[].standard boolean    
schema.attributes[].strictOverride boolean    
schema.attributes[].what string    
schema.objectClasses list    
schema.objectClasses[].name string    
schema.objectClasses[].standard boolean    
schema.objectClasses[].what string    
schema.objectClasses[].where string    
shown integer    
sourceOfTruth string    

GET /admin-api/ldap/policies

getDirectoryPolicies

The policy repository as the directory holds it, and its schema

ou=policies IS the XACML policy repository, the way ou=federations is the federation register. One entry per policy or policy set, holding the document itself, with exactly one of them the root — a PDP evaluates one document and reaches the rest through PolicyIdReference.

A WRITE HERE SKIPS THE TYPECHECKER, and that is the one thing this operation says that GET /admin-api/xacml/policies does not. Every write through the console and through /admin-api/xacml parses the document and statically typechecks it, so a policy that does not typecheck is refused at WRITE time rather than going Indeterminate on every request. An ldapmodify of xacmlPolicyDocument reaches the entry directly and skips all of it, and nothing caches these entries.

Mirrors GET /admin/ldap/policies on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of a policy name, a DN, or any value on the entry — the DOCUMENT included, so this finds the policy that names a particular resource.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The page of policy entries and the schema.

Member Type Required What it is
applicationCount integer    
applicationMax integer    
baseDn string    
container string    
count integer    
directory boolean    
enabledCount integer    
filter object    
filter.q string, or null    
firstRow integer    
lastRow integer    
matched integer    
max integer    
message string    
ownCount integer    
page integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
perPage integer    
policies list    
policies[].attributes map   Attribute names, which are data in a schemaless directory, and values.
policies[].attributes.{key} list, or string, or null    
policies[].attributes.{key}[] string    
policies[].createdAt string, or null    
policies[].dn string    
policies[].modifiedAt string, or null    
policies[].name string    
policies[].operational list    
policies[].operational[] string    
policies[].origin string, or null    
schema object    
schema.attributes list    
schema.attributes[].editable boolean, or string    
schema.attributes[].enum list    
schema.attributes[].enum[] string    
schema.attributes[].families list    
schema.attributes[].families[] string    
schema.attributes[].familyWhy string    
schema.attributes[].from string    
schema.attributes[].identifier boolean    
schema.attributes[].identifierName string    
schema.attributes[].kind string    
schema.attributes[].name string    
schema.attributes[].overrides string    
schema.attributes[].role string    
schema.attributes[].secret boolean    
schema.attributes[].sensitive boolean    
schema.attributes[].standard boolean    
schema.attributes[].strictOverride boolean    
schema.attributes[].what string    
schema.objectClasses list    
schema.objectClasses[].name string    
schema.objectClasses[].standard boolean    
schema.objectClasses[].what string    
schema.objectClasses[].where string    
shown integer    
sourceOfTruth string    

GET /admin-api/ldap/roles

getDirectoryRoles

The role entries as the directory holds them, and their schema

THIS CONTAINER IS HALF THE FEATURE. A role has two relations and they are stored apart on purpose: MEMBERSHIP — who holds it — is here on the role entry, and the REQUIREMENT — which roles an application demands before anything is issued for it — is appRequiredRole on the APPLICATION entry, under a different container. So nothing in this reply refuses anybody by itself, and a caller looking for the reason somebody was turned away wants GET /admin-api/roles, which resolves both halves.

THE SIX BUILT-IN ROLES ARE IN NO CONTAINER. They are computed from the context of the decision being made, so EVERYBODY has no entry here and never will — which is why an empty roles array is the ORDINARY state of a service refusing nobody rather than a sign that the feature is not loaded.

THE ENTRIES ARE THE REGISTER: nothing caches them, so an ldapmodify adding a value to roleMemberUser is answered by the very next issuance decision.

Mirrors GET /admin/ldap/roles on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of a role name, a DN, or any value on the entry — which includes its members, so this is how to find the roles one person holds by name.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The page of role entries, the six built-in names and the schema.

Member Type Required What it is
baseDn string    
builtIn list    
builtIn[] string    
builtInCatalogue list    
builtInCatalogue[].name string    
builtInCatalogue[].what string    
container string    
count integer    
directory boolean    
filter object    
filter.q string, or null    
firstRow integer    
lastRow integer    
matched integer    
max integer    
message string    
page integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
perPage integer    
roles list    
roles[].attributes map   Attribute names, which are data in a schemaless directory, and values.
roles[].attributes.{key} list, or string, or null    
roles[].attributes.{key}[] string    
roles[].createdAt string, or null    
roles[].dn string    
roles[].modifiedAt string, or null    
roles[].name string    
roles[].operational list    
roles[].operational[] string    
roles[].origin string, or null    
schema object    
schema.attributes list    
schema.attributes[].editable boolean, or string    
schema.attributes[].enum list    
schema.attributes[].enum[] string    
schema.attributes[].families list    
schema.attributes[].families[] string    
schema.attributes[].familyWhy string    
schema.attributes[].from string    
schema.attributes[].identifier boolean    
schema.attributes[].identifierName string    
schema.attributes[].kind string    
schema.attributes[].name string    
schema.attributes[].overrides string    
schema.attributes[].role string    
schema.attributes[].secret boolean    
schema.attributes[].sensitive boolean    
schema.attributes[].standard boolean    
schema.attributes[].strictOverride boolean    
schema.attributes[].what string    
schema.objectClasses list    
schema.objectClasses[].name string    
schema.objectClasses[].standard boolean    
schema.objectClasses[].what string    
schema.objectClasses[].where string    
shown integer    
sourceOfTruth string    

GET /admin-api/ldap/service

getDirectoryService

What the embedded directory IS, right now

The two raw sockets and the store behind them AS THEY ACTUALLY ARE: whether TCP 389 and LDAPS 636 really bound and the error if either did not, the base DN and each realm’s naming context, what a subtree search from each one answers about, the bind policy, the four structural rules this directory does still enforce, the entry count and the persistence status.

WHY IT IS NOT GET /admin-api/ldap: that operation is the six ldap.* SETTINGS — what the sockets are configured to be. This one is what happened. A host whose own slapd already holds 389 makes the two disagree, and nothing else in this service can report that: /admin/sts-metadata is built by walking the express router and a raw TCP listener is not on it.

NO BIND IS EVER REFUSED here, by any setting, except the one literal password named in refusedPassword — which exists so a negative test has something to fail on.

Mirrors GET /admin/ldap/service on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The directory as it is right now.

Member Type Required What it is
authenticationFacts string    
autoCreateRule string    
autoCreateUsers boolean    
baseDn string    
bindPolicy string    
certificateProvenance string, or null    
directory boolean    
enforcedRules list    
enforcedRules[] string    
groupsDn string    
implementation string    
ldapPort integer, or null    
ldapVersion integer    
ldapsPort integer, or null    
limits object    
limits.currentEntries number    
limits.currentEntriesEverywhere number    
limits.maxEntries number    
limits.maxSearchResults number    
listenError string, or null    
listening boolean    
message string    
namingContexts list    
namingContexts[] string    
operations list    
operations[] string    
persistence object    
persistence.answersAfterCommit boolean    
persistence.cells object    
persistence.cells.cell string, or null    
persistence.cells.globalReplication object    
persistence.cells.globalReplication.appliedSeq number    
persistence.cells.globalReplication.byKind map   A count per name.
persistence.cells.globalReplication.byKind.{key} number    
persistence.cells.globalReplication.coordinating boolean    
persistence.cells.globalReplication.failures number    
persistence.cells.globalReplication.highestSeq number    
persistence.cells.globalReplication.holeRanges number    
persistence.cells.globalReplication.holes number    
persistence.cells.globalReplication.holesAbandoned number    
persistence.cells.globalReplication.lastError string, or null    
persistence.cells.globalReplication.lastPullAt number, or string, or null    
persistence.cells.globalReplication.note string    
persistence.cells.globalReplication.nudges number    
persistence.cells.globalReplication.originsDropped number    
persistence.cells.globalReplication.otherProcesses number    
persistence.cells.globalReplication.pollIntervalMs number    
persistence.cells.globalReplication.pulls number    
persistence.cells.globalReplication.retention object    
persistence.cells.globalReplication.retention.declaredGoneAt number, or string, or null    
persistence.cells.globalReplication.retention.fanInGraceS number    
persistence.cells.globalReplication.retention.lastTrim object    
persistence.cells.globalReplication.retention.lastTrim.at string    
persistence.cells.globalReplication.retention.lastTrim.bound number, or null    
persistence.cells.globalReplication.retention.lastTrim.error string, or null    
persistence.cells.globalReplication.retention.lastTrim.readers number    
persistence.cells.globalReplication.retention.lastTrim.readersGone number    
persistence.cells.globalReplication.retention.lastTrim.trimmed number    
persistence.cells.globalReplication.retention.readerTtlS number    
persistence.cells.globalReplication.retention.reportError string, or null    
persistence.cells.globalReplication.retention.reportedAt string, or null    
persistence.cells.globalReplication.retention.retentionS number    
persistence.cells.globalReplication.retention.trimming boolean    
persistence.cells.globalReplication.rowsApplied number    
persistence.cells.globalReplication.startedAt number, or string, or null    
persistence.cells.globalReplication.supported boolean    
persistence.cells.jurisdiction string, or null    
persistence.cells.routing object    
persistence.cells.routing.conflicts number    
persistence.cells.routing.indexed number    
persistence.cells.routing.lastConflict string, or null    
persistence.cells.routing.projectionWrites number    
persistence.commitBacklog boolean    
persistence.configuredMode string    
persistence.coordinates boolean    
persistence.dataDir string, or null    
persistence.database object    
persistence.database.caFile string, or null    
persistence.database.database string, or null    
persistence.database.encrypted boolean    
persistence.database.host string, or null    
persistence.database.note string    
persistence.database.passwordFrom string    
persistence.database.passwordProvider string    
persistence.database.passwordSecret object    
persistence.database.passwordSecret.configured boolean    
persistence.database.passwordSecret.field string    
persistence.database.passwordSecret.known boolean    
persistence.database.passwordSecret.label string    
persistence.database.passwordSecret.provider string    
persistence.database.passwordSecret.providers list    
persistence.database.passwordSecret.providers[].id string    
persistence.database.passwordSecret.providers[].label string    
persistence.database.passwordSecret.secret string    
persistence.database.passwordSecret.shared boolean    
persistence.database.passwordSecret.where object    
persistence.database.passwordSecret.where.authenticates string    
persistence.database.passwordSecret.where.endpoint string    
persistence.database.passwordSecret.where.field string    
persistence.database.passwordSecret.where.from string    
persistence.database.passwordSecret.where.region string    
persistence.database.passwordSecret.where.shared boolean    
persistence.database.passwordSecret.where.vault string    
persistence.database.passwordSecret.where.wraps string    
persistence.database.port string, or null    
persistence.database.sslmode string    
persistence.database.tls string    
persistence.database.user string, or null    
persistence.database.verifyCertificate boolean    
persistence.enabled boolean    
persistence.engine string, or null    
persistence.entriesTracked number    
persistence.eventLoop object    
persistence.eventLoop.lastReport object    
persistence.eventLoop.lastReport.at string    
persistence.eventLoop.lastReport.maxMs number    
persistence.eventLoop.lastReport.meanMs number    
persistence.eventLoop.lastReport.p99Ms number    
persistence.eventLoop.sinceReport object    
persistence.eventLoop.sinceReport.at string    
persistence.eventLoop.sinceReport.maxMs number    
persistence.eventLoop.sinceReport.meanMs number    
persistence.eventLoop.sinceReport.p99Ms number    
persistence.eventLoop.warnAboveMs number    
persistence.failures number    
persistence.healthy boolean, or null    
persistence.lastError string, or null    
persistence.lastWriteAt number, or string, or null    
persistence.liveness object    
persistence.liveness.connects number    
persistence.liveness.drops number    
persistence.liveness.open boolean    
persistence.liveness.queries number    
persistence.liveness.viaPool number    
persistence.minted object    
persistence.minted.droppedPoison number    
persistence.minted.droppedUnknown number    
persistence.minted.droppedUnreadable number    
persistence.minted.failures number    
persistence.minted.handles list    
persistence.minted.handles[].handle string    
persistence.minted.handles[].scope string    
persistence.minted.handles[].shape string    
persistence.minted.lastError string, or null    
persistence.minted.lastWriteAt number, or string, or null    
persistence.minted.mode string    
persistence.minted.pending number    
persistence.minted.persisting boolean    
persistence.minted.poisonDrops list    
persistence.minted.poisonDrops[].at string    
persistence.minted.poisonDrops[].code string    
persistence.minted.poisonDrops[].handles list    
persistence.minted.poisonDrops[].handles[] string    
persistence.minted.poisonDrops[].message string    
persistence.minted.poisonDrops[].realms list    
persistence.minted.poisonDrops[].realms[] string    
persistence.minted.poisonDrops[].rows number    
persistence.minted.restored number    
persistence.minted.restoredAt number, or string, or null    
persistence.minted.retentionMs number    
persistence.minted.rowsDeleted number    
persistence.minted.rowsWritten number    
persistence.minted.sealed boolean    
persistence.minted.setting boolean    
persistence.minted.shared number    
persistence.minted.stores number    
persistence.minted.supported boolean    
persistence.minted.unsupportedReason string    
persistence.minted.writes number    
persistence.mode string    
persistence.note string    
persistence.origin object    
persistence.origin.adopted boolean    
persistence.origin.origin string, or null    
persistence.origin.why string    
persistence.pending boolean    
persistence.persistsAppconfig boolean    
persistence.persistsDirectory boolean    
persistence.persistsRealms boolean    
persistence.realmsTracked number    
persistence.replication object    
persistence.replication.appliedSeq number    
persistence.replication.byKind map   A count per name.
persistence.replication.byKind.{key} number    
persistence.replication.coordinating boolean    
persistence.replication.failures number    
persistence.replication.highestSeq number    
persistence.replication.holeRanges number    
persistence.replication.holes number    
persistence.replication.holesAbandoned number    
persistence.replication.lastError string, or null    
persistence.replication.lastPullAt number, or string, or null    
persistence.replication.note string    
persistence.replication.nudges number    
persistence.replication.originsDropped number    
persistence.replication.otherProcesses number    
persistence.replication.pollIntervalMs number    
persistence.replication.pulls number    
persistence.replication.retention object    
persistence.replication.retention.declaredGoneAt number, or string, or null    
persistence.replication.retention.fanInGraceS number    
persistence.replication.retention.lastTrim object    
persistence.replication.retention.lastTrim.at string    
persistence.replication.retention.lastTrim.bound number, or null    
persistence.replication.retention.lastTrim.error string, or null    
persistence.replication.retention.lastTrim.readers number    
persistence.replication.retention.lastTrim.readersGone number    
persistence.replication.retention.lastTrim.trimmed number    
persistence.replication.retention.readerTtlS number    
persistence.replication.retention.reportError string, or null    
persistence.replication.retention.reportedAt string, or null    
persistence.replication.retention.retentionS number    
persistence.replication.retention.trimming boolean    
persistence.replication.rowsApplied number    
persistence.replication.startedAt number, or string, or null    
persistence.replication.supported boolean    
persistence.restored object    
persistence.restored.entries number    
persistence.restored.overrides number    
persistence.restored.realms number    
persistence.restoredAt number, or string, or null    
persistence.retryArmed boolean    
persistence.usedAssertions object    
persistence.usedAssertions.atomicAcrossProcesses boolean    
persistence.usedAssertions.cap number    
persistence.usedAssertions.kind string, or null    
persistence.usedAssertions.live number, or null    
persistence.usedAssertions.liveIsCurrent boolean    
persistence.usedAssertions.persistent boolean    
persistence.usedAssertions.store string, or null    
persistence.usedAssertions.why string, or null    
persistence.writeDelayMs number    
persistence.writes number    
port integer, or null    
referentialIntegrity boolean    
refusedPassword string    
schema string    
searchScope string    
specifications list    
specifications[] string    
tls object    
tls.certificate object    
tls.certificate.fingerprint256 string, or null    
tls.certificate.names list    
tls.certificate.names[] string    
tls.certificate.notAfter string, or null    
tls.certificate.source string    
tls.certificate.subject string, or null    
tls.clientCertificateMode string    
tls.clientCertificates string    
tls.error string, or null    
tls.ldaps boolean    
tls.listening boolean    
tls.port integer, or null    
tls.saslExternal object    
tls.saslExternal.available boolean    
tls.saslExternal.mechanisms list    
tls.saslExternal.mechanisms[] string    
tls.saslExternal.outsideCertificateAuthorities boolean    
tls.saslExternal.rule string    
tls.startTls boolean    
tls.url string    
url string    
usersDn string    

GET /admin-api/ldap/spiffe

getDirectorySpiffe

The two SPIFFE containers as the directory holds them, and their schema

THE TWO CONTAINERS HOLD DIFFERENT KINDS OF THING, which is why they are two. ou=entries is CONFIGURATION — which SPIFFE ID a workload gets, under which parent, matching which selectors — and ou=agents is a RECORD of what has attested, which is why nothing about an agent is editable anywhere.

THE ENTRIES ARE THE REGISTRY: nothing caches them, so an ldapmodify of spiffeX509SvidTtl changes the lifetime of the next SVID the Workload API hands out.

THIS IS THE ONE DIRECTORY OPERATION WITH TWO LISTS IN IT, so it pages the way the console’s drill-downs do: entriesPage and agentsPage move one list each and per is shared, with an entriesPaging and an agentsPaging object in the reply. entries and agents at the top level are the TOTALS and not the page.

Mirrors GET /admin/ldap/spiffe on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
entryq query string   Substring of a registration entry’s SPIFFE ID or DN.
agentq query string   Substring of an attested agent’s id or DN.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
entriesPage query integer   Which page of entries to return, answered by entriesPaging. The registration entries.
agentsPage query integer   Which page of agents to return, answered by agentsPaging. The attested agents.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The two pages, the two containers and the schema.

Member Type Required What it is
agents integer    
agentsContainer string    
agentsPaging object    
agentsPaging.firstRow integer    
agentsPaging.lastRow integer    
agentsPaging.noun string, or null    
agentsPaging.page integer    
agentsPaging.pages integer    
agentsPaging.param string, or null    
agentsPaging.perPage integer    
agentsPaging.total integer    
attestedAgents list    
attestedAgents[].attestationType string    
attestedAgents[].attestations number    
attestedAgents[].attributes map   Attribute names, which are data in a schemaless directory, and values.
attestedAgents[].attributes.{key} list, or string, or null    
attestedAgents[].attributes.{key}[] string    
attestedAgents[].banned boolean    
attestedAgents[].canReattest boolean    
attestedAgents[].dn string    
attestedAgents[].expiresAt number    
attestedAgents[].firstSeen string    
attestedAgents[].id string    
attestedAgents[].lastSeen string    
attestedAgents[].selectors list    
attestedAgents[].selectors[].type string    
attestedAgents[].selectors[].value string    
attestedAgents[].svidHash string    
baseDn string    
container string    
directory boolean    
editable list    
editable[] string    
entries integer    
entriesContainer string    
entriesPaging object    
entriesPaging.firstRow integer    
entriesPaging.lastRow integer    
entriesPaging.noun string, or null    
entriesPaging.page integer    
entriesPaging.pages integer    
entriesPaging.param string, or null    
entriesPaging.perPage integer    
entriesPaging.total integer    
filter object    
filter.agentq string, or null    
filter.entryq string, or null    
maxAgents integer    
maxEntries integer    
message string    
registrationEntries list    
registrationEntries[].admin boolean    
registrationEntries[].attributes map   Attribute names, which are data in a schemaless directory, and values.
registrationEntries[].attributes.{key} list, or string, or null    
registrationEntries[].attributes.{key}[] string    
registrationEntries[].createdAt string    
registrationEntries[].dn string    
registrationEntries[].dnsNames list    
registrationEntries[].dnsNames[] string    
registrationEntries[].downstream boolean    
registrationEntries[].expired boolean    
registrationEntries[].expiresAt number    
registrationEntries[].federatesWith list    
registrationEntries[].federatesWith[] string    
registrationEntries[].hint string    
registrationEntries[].id string    
registrationEntries[].jwtSvidTtl number    
registrationEntries[].lastSvidAt string    
registrationEntries[].modifiedAt string    
registrationEntries[].origin string    
registrationEntries[].parentId string    
registrationEntries[].revisionNumber number    
registrationEntries[].selectorTexts list    
registrationEntries[].selectorTexts[] string    
registrationEntries[].selectors list    
registrationEntries[].selectors[].type string    
registrationEntries[].selectors[].value string    
registrationEntries[].spiffeId string    
registrationEntries[].storeSvid boolean    
registrationEntries[].svidsIssued number    
registrationEntries[].x509SvidTtl number    
schema object    
schema.attributes list    
schema.attributes[].editable boolean, or string    
schema.attributes[].enum list    
schema.attributes[].enum[] string    
schema.attributes[].families list    
schema.attributes[].families[] string    
schema.attributes[].familyWhy string    
schema.attributes[].from string    
schema.attributes[].identifier boolean    
schema.attributes[].identifierName string    
schema.attributes[].kind string    
schema.attributes[].name string    
schema.attributes[].overrides string    
schema.attributes[].role string    
schema.attributes[].secret boolean    
schema.attributes[].sensitive boolean    
schema.attributes[].standard boolean    
schema.attributes[].strictOverride boolean    
schema.attributes[].what string    
schema.objectClasses list    
schema.objectClasses[].name string    
schema.objectClasses[].standard boolean    
schema.objectClasses[].what string    
schema.objectClasses[].where string    
sourceOfTruth string