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/tls

getTlsSettings

The TLS certificate’s own settings

The tls.* settings: the hostnames and IP addresses that go into the self-signed certificate this service mints on every start, and what it makes of a CLIENT’s.

THE CERTIFICATE ONES ARE RESTART-ONLY: it is minted before anything is listening. One certificate serves LDAPS 636 and — when global.https is on — the main port, so a caller trusts this service once rather than twice.

THERE ARE NO PORTS HERE SINCE 2026-09-16, when tls.port (8443) and tls.mutualPort (9443) were removed with the two listeners they named: the main port already asks every connection for a client certificate and requires none of any of them.

Whether the MAIN port is HTTPS is global.https, which is on GET /config with the rest of the process’s own settings: it is a fact about the process rather than about this certificate, and it defaults to whatever oauth2.rfc9700 is.

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/tls 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/tls-connection

getTlsConnection

What this service saw of THIS request: its TLS connection, its client certificate and its forwarding headers

Describes the request that asked — and only that one — as this service saw and believed it. connection: https, encrypted, the TLS protocol and cipher negotiated, the socket’s peerAddress and the clientAddress this service believes. clientCertificate: whether one was presented on the connection, whether it verified against the client truststore (GET /admin-api/tls/trust) or the authorizationError OpenSSL gave, the certificate (subject, issuer, serial, validity, subjectAltName, key, SHA-256 fingerprint and PEM), its RFC 8705 thumbprint, what the identity gate made of it (identity: issued here, accepted, kind, username, realm, why not) and the revocation verdict GET /tls/sign-in would act on. forwarded: global.trustProxy and global.trustedProxies, whether the peer is a trusted proxy and whether the forwarding headers were believed, the effectiveBaseUrl every issuer and endpoint is built from, each forwarding header with its value, and the client-certificate headers a proxy might set — which this service READS NONE OF, in either mode.

IT CHANGES NOTHING: no session is started (that is GET /tls/sign-in), no sighting recorded, no setting written.

THE CONSOLE’S PAGE DESCRIBES ITS OWN CALL TO THIS OPERATION, not the request that loaded the page: the console is a static application, so the view is a second request, on whatever connection the browser chose for it. Answered by the front process, which holds the client’s socket. Development only as GET /tls and GET /tls/forwarded until #597.

Mirrors GET /admin/tls-connection 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 request’s connection, client certificate and forwarding headers.

Member Type Required What it is
clientCertificate object    
clientCertificate.authorizationError string, or null    
clientCertificate.certificate object    
clientCertificate.certificate.curve string, or null    
clientCertificate.certificate.depth integer    
clientCertificate.certificate.extendedKeyUsage list    
clientCertificate.certificate.extendedKeyUsage[] string    
clientCertificate.certificate.fingerprint256 string, or null    
clientCertificate.certificate.issuer string, or null    
clientCertificate.certificate.keySize number, or null    
clientCertificate.certificate.pem string, or null    
clientCertificate.certificate.serialNumber string, or null    
clientCertificate.certificate.subject string, or null    
clientCertificate.certificate.subjectAltName string, or null    
clientCertificate.certificate.validFrom string, or null    
clientCertificate.certificate.validTo string, or null    
clientCertificate.handshakeVerified boolean    
clientCertificate.identity object    
clientCertificate.identity.accepted boolean    
clientCertificate.identity.issuedHere boolean    
clientCertificate.identity.kind string, or null    
clientCertificate.identity.realm string, or null    
clientCertificate.identity.username string, or null    
clientCertificate.identity.why string, or null    
clientCertificate.note string    
clientCertificate.presented boolean    
clientCertificate.revocation object    
clientCertificate.revocation.checked boolean    
clientCertificate.revocation.links list    
clientCertificate.revocation.links[].answeredBy string    
clientCertificate.revocation.links[].authority object    
clientCertificate.revocation.links[].authority.ca string, or null    
clientCertificate.revocation.links[].authority.label string    
clientCertificate.revocation.links[].authority.scope string, or null    
clientCertificate.revocation.links[].crlFromCache boolean    
clientCertificate.revocation.links[].crlNextUpdate string, or null    
clientCertificate.revocation.links[].crlUrl string    
clientCertificate.revocation.links[].deltaUrl string    
clientCertificate.revocation.links[].depth integer    
clientCertificate.revocation.links[].distributionPoints list    
clientCertificate.revocation.links[].distributionPoints[] string    
clientCertificate.revocation.links[].indirect boolean    
clientCertificate.revocation.links[].invalid boolean    
clientCertificate.revocation.links[].issuer string, or null    
clientCertificate.revocation.links[].noRevAvail boolean    
clientCertificate.revocation.links[].notDialled list    
clientCertificate.revocation.links[].notDialled[] string    
clientCertificate.revocation.links[].ocspFromCache boolean    
clientCertificate.revocation.links[].ocspNextUpdate string, or null    
clientCertificate.revocation.links[].ocspNonce boolean, or string, or null    
clientCertificate.revocation.links[].ocspOrder string    
clientCertificate.revocation.links[].ocspResponder string, or null    
clientCertificate.revocation.links[].ocspResponderStatus string    
clientCertificate.revocation.links[].ocspUrl string    
clientCertificate.revocation.links[].reason string, or null    
clientCertificate.revocation.links[].reasonCode number, or null    
clientCertificate.revocation.links[].refusable boolean    
clientCertificate.revocation.links[].revokedAt string, or null    
clientCertificate.revocation.links[].serialHex string, or null    
clientCertificate.revocation.links[].source string    
clientCertificate.revocation.links[].status string    
clientCertificate.revocation.links[].subject string, or null    
clientCertificate.revocation.links[].unknownKind string    
clientCertificate.revocation.links[].why string    
clientCertificate.revocation.noRevAvail list    
clientCertificate.revocation.noRevAvail[] string    
clientCertificate.revocation.notDialled list    
clientCertificate.revocation.notDialled[] string    
clientCertificate.revocation.policy string    
clientCertificate.revocation.policyConfigured string    
clientCertificate.revocation.refused boolean    
clientCertificate.revocation.revoked object    
clientCertificate.revocation.revoked.answeredBy string    
clientCertificate.revocation.revoked.depth integer    
clientCertificate.revocation.revoked.reason string, or null    
clientCertificate.revocation.revoked.reasonCode number, or null    
clientCertificate.revocation.revoked.revokedAt string, or null    
clientCertificate.revocation.revoked.serialHex string, or null    
clientCertificate.revocation.revoked.source string    
clientCertificate.revocation.revoked.subject string, or null    
clientCertificate.revocation.status string    
clientCertificate.revocation.unknown list    
clientCertificate.revocation.unknown[].depth integer    
clientCertificate.revocation.unknown[].invalid boolean    
clientCertificate.revocation.unknown[].kind string    
clientCertificate.revocation.unknown[].notDialled list    
clientCertificate.revocation.unknown[].notDialled[] string    
clientCertificate.revocation.unknown[].refusable boolean    
clientCertificate.revocation.unknown[].subject string, or null    
clientCertificate.revocation.unknown[].why string    
clientCertificate.revocation.why string    
clientCertificate.revocationStatus object    
clientCertificate.revocationStatus.checked boolean    
clientCertificate.revocationStatus.policy string    
clientCertificate.revocationStatus.refused boolean    
clientCertificate.revocationStatus.source string    
clientCertificate.revocationStatus.status string    
clientCertificate.signIn string    
clientCertificate.thumbprint string, or null    
clientCertificate.verified boolean    
connection object    
connection.cipher string, or null    
connection.clientAddress string, or null    
connection.encrypted boolean    
connection.https boolean    
connection.peerAddress string, or null    
connection.protocol string, or null    
forwarded object    
forwarded.believed boolean    
forwarded.clientCertificateHeaders object    
forwarded.clientCertificateHeaders.headers list    
forwarded.clientCertificateHeaders.headers[].header string    
forwarded.clientCertificateHeaders.headers[].present boolean    
forwarded.clientCertificateHeaders.headers[].value string, or null    
forwarded.clientCertificateHeaders.headers[].what string    
forwarded.clientCertificateHeaders.note string    
forwarded.clientCertificateHeaders.readByThisService boolean    
forwarded.clientCertificateHeaders.seen list    
forwarded.clientCertificateHeaders.seen[] string    
forwarded.effectiveBaseUrl string    
forwarded.forwarding list    
forwarded.forwarding[].header string    
forwarded.forwarding[].present boolean    
forwarded.forwarding[].value string, or null    
forwarded.forwarding[].what string    
forwarded.peerIsTrustedProxy boolean    
forwarded.proxyMustSanitize string    
forwarded.rangesConfigured number    
forwarded.rangesUsable number    
forwarded.socket object    
forwarded.socket.encrypted boolean    
forwarded.socket.host string    
forwarded.socket.scheme string    
forwarded.trustProxy boolean    
forwarded.trustedProxies list    
forwarded.trustedProxies[] string    
forwarded.whatItMeans string    
generatedAt string    

GET /admin-api/tls/trust

getTruststore

Every client-certificate trust anchor, and where each came from

The anchors LDAPS 636 and the main HTTPS port verify a CLIENT certificate against. A certificate that chains to one of these is verified, and a verified certificate is an identity here — it starts a sign-on session and it is what admits a remote XACML PEP to /xacml/pep/* — so this list is whose certificates this service believes.

Each row carries the subject, issuer, serial, validity, SHA-256 fingerprint (the colon form openssl x509 -fingerprint -sha256 prints), whether it is a CA, the PEM, and source: file for one read from tls.trustAnchorsFile at startup, runtime for one added while the process was running, with persisted saying whether it was written down.

A RUNTIME ANCHOR IS PERSISTED in ou=trustAnchors in the default realm’s directory, so it survives a restart wherever the directory does (persistence.mode ldif or postgres) and reaches every other process against the same store. A file anchor is not stored there and comes back at the next start however it was removed.

ONE TRUSTSTORE FOR THE PROCESS, NOT PER REALM. The sockets that verify a client certificate are shared by every trust realm, so this answers the same list under every realm prefix.

NO PRIVATE KEY IS IN THIS REPLY — the truststore holds certificates and nothing else.

Mirrors GET /admin/tls/trust 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
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 anchors on this page with their paging, the counts by source, the configured anchors file, and which doors can change the list.

Member Type Required What it is
actions list    
actions[] string    
anchors list    
anchors[].addedAt string    
anchors[].ca boolean    
anchors[].fingerprint256 string    
anchors[].issuer string, or null    
anchors[].notAfter string, or null    
anchors[].notBefore string, or null    
anchors[].pem string    
anchors[].persisted boolean    
anchors[].readable boolean    
anchors[].serial string, or null    
anchors[].source string    
anchors[].subject string, or null    
anchors[].unadmittable string    
anchorsFile string    
atRuntime integer    
doors object    
doors.api string    
doors.console string    
fromFile integer    
installed boolean    
loadedFromFile number, or null    
max integer    
note string    
notes object    
notes.effect string    
notes.persisted string    
notes.revocation string    
notes.scope 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    
persisted boolean    
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    
total integer    

503: The answer.

Member Type Required What it is
actions list    
actions[] string    
anchors list    
anchors[].addedAt string    
anchors[].ca boolean    
anchors[].fingerprint256 string    
anchors[].issuer string, or null    
anchors[].notAfter string, or null    
anchors[].notBefore string, or null    
anchors[].pem string    
anchors[].persisted boolean    
anchors[].readable boolean    
anchors[].serial string, or null    
anchors[].source string    
anchors[].subject string, or null    
anchors[].unadmittable string    
anchorsFile string    
atRuntime integer    
doors object    
doors.api string    
doors.console string    
fromFile integer    
installed boolean    
loadedFromFile number, or null    
max integer    
note string    
notes object    
notes.effect string    
notes.persisted string    
notes.revocation string    
notes.scope 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    
persisted boolean    
protocolEndpoints list    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
total integer    

POST /admin-api/tls/trust/add

addTrustAnchors

Trust client certificates issued by one or more CAs

Adds every -----BEGIN CERTIFICATE----- block in certificates — the root, or the whole chain above the leaf — and applies the new truststore to every listener with setSecureContext(). The next handshake is judged against it; connections already open keep the truststore they were made under.

ALL OR NOTHING ON A BLOCK OPENSSL CANNOT READ. If any block does not parse, none is added: an anchor the listener cannot parse makes the next truststore change throw on every listener. A certificate already held is counted in duplicates and not added twice. The truststore holds at most 32 anchors; an add that fills it keeps what went in and says why the rest did not in warning.

PERSISTED in ou=trustAnchors wherever the directory is; persisted in the reply says whether every anchor this call added was written down.

THIS IS THE ONE WAY TO ADD AN ANCHOR AT RUNTIME, beside the console page that mirrors it, in both modes: the open POST /tls/trust was deleted. The reply names what was added and carries no private key, because none is involved.

Mirrors POST /admin/tls/trust on the admin console.

Scope: admin:write.

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.

Request body

Member Type Required What it is
certificates string yes One or more PEM certificates, concatenated. An array of PEM strings is accepted too.

200: How many anchors were added, how many were already held, the new total, and the subject and fingerprint of each one added.

Member Type Required What it is
added number    
addedAnchors list    
addedAnchors[].fingerprint256 string, or null    
addedAnchors[].source string, or null    
addedAnchors[].subject string, or null    
anchors number    
duplicates number    
errors list    
errors[] string    
message string    
ok boolean yes  
persisted boolean    
warning string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added number    
addedAnchors list    
addedAnchors[].fingerprint256 string, or null    
addedAnchors[].source string, or null    
addedAnchors[].subject string, or null    
anchors number    
duplicates number    
errors list    
errors[] string    
message string    
ok boolean yes  
persisted boolean    
warning string    

POST /admin-api/tls/trust/remove

removeTrustAnchor

Stop trusting one anchor, named by its fingerprint

Removes the ONE anchor whose SHA-256 fingerprint is fingerprint — colon-separated or plain hex, either case — and applies the smaller truststore to every listener.

THERE IS NO BULK CLEAR ON THIS API, AND THAT IS DELIBERATE. A clear is the one change whose reach is every client certificate every other caller relies on, and the open POST /tls/trust/clear that did it was deleted. Remove the rows you mean.

A file ANCHOR MAY BE REMOVED AND COMES BACK AT THE NEXT START, when tls.trustAnchorsFile is read again; the reply says so. A fingerprint this truststore does not hold is refused and removes nothing.

Mirrors POST /admin/tls/trust on the admin console.

Scope: admin:write.

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.

Request body

Member Type Required What it is
fingerprint string yes The anchor’s SHA-256 fingerprint, as GET /admin-api/tls/trust lists it in fingerprint256.

200: The anchor that was removed, where it came from, and the new total.

Member Type Required What it is
anchors number    
errors list    
errors[] string    
message string    
ok boolean yes  
persisted boolean    
removed number    
removedAnchor object    
removedAnchor.fingerprint256 string, or null    
removedAnchor.source string, or null    
removedAnchor.subject string, or null    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
anchors number    
errors list    
errors[] string    
message string    
ok boolean yes  
persisted boolean    
removed number    
removedAnchor object    
removedAnchor.fingerprint256 string, or null    
removedAnchor.source string, or null    
removedAnchor.subject string, or null