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

Management API

What this API is, its document, and the explorer that calls it.

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

getIndex

What this API is, and every operation in it

The index. Every operation with the console control it mirrors, and where the OpenAPI document and the explorer are. Nothing here changes anything.

Mirrors GET /admin 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 index.

Member Type Required What it is
build string   The build number on its own: the UTC build instant as YYYYMMDDHHMMSS, or the BUILD_NUMBER a release build named. Absent on a stamp that carries none.
builtAt string   When this build was made. Read it with stamped.
commit string   The first twelve characters of the commit this was built from. Absent when the build could not know it.
console string   Where the console every operation mirrors is.
docs string   Where the explorer is.
name string    
openapi string   Where the document is.
operations list   Every management operation, with the console page it mirrors. The console’s own operations are listed by GET /admin-api/console/operations (#454).
operations[] object   One operation.
operations[].drawnOn list   The console pages drawn from this operation’s data by one of the console’s own operations (#454); present only where there are any.
operations[].drawnOn[] string    
operations[].kind one of management, console   Which of the two kinds the operation is (#454).
operations[].method string    
operations[].mirrors string   The /admin control this operation is the API form of.
operations[].operationId string    
operations[].path string    
operations[].summary string    
protected boolean   Whether this API requires an access token (adminApi.authRequired, on by default).
release boolean   True when this build was flagged as a release (STS_RELEASE=true) and named its build number.
stamped boolean   True when this version came off a record written at image build time. False means the process computed its own record at startup, so builtAt and the build number are the moment it started.
version string   M.N.O.<build>: the release the repo-root VERSION file declares, followed by the build number. A stamp written before build numbers returned (#1317) reports the bare M.N.O.

GET /admin-api/account-api

getAccountApi

The account API’s OpenAPI document

The OpenAPI 3.1 document of /account-api — the user portal’s API — for the realm the call is in (document), where that API publishes it (url), and how many paths and operations it holds. The same document GET /account-api/openapi.json answers, built from the table that registers those routes.

Mirrors GET /admin/account-api 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 document and where it is published.

Member Type Required What it is
document object   An OpenAPI 3.1.0 document.
document.components any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
document.info any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
document.openapi string    
document.paths any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
document.security any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
document.servers any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
document.tags any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
operations integer   Operations in the document.
paths integer   Paths in the document.
url string   Where the account API publishes the document itself.

GET /admin-api/caches

getCaches

Every cache this service holds, or one cache’s entries

Without cache: every cache registered with common/cache_registry.js — name, title, description, owner, scope (process or realm), size (entries held now), valid, expired (past their deadline, or built from something that has since changed, and not evicted yet), maxEntries (the bound — PER REALM for a realm scope; every store has one since 2026-09-18, and null means its owner regressed, shown in problem as STS-CORE-0096), largestRealm (the fullest realm’s rows, the figure to compare with a per-realm bound), bound (whether the bound is enforced or structural, in a sentence), atBound, evictions and refusals (entries dropped or inserts refused at the bound), lifetime, settings, hits, misses and hitRatio (null before any lookup) — plus totals, notListed (what this process does not hold between requests) and otherProcesses: each other cluster node’s last published snapshot (and this node’s front process when a request worker answers), with nodeId, name, host, pid, takenAt, ageSeconds, totals and per store name, size, largestRealm, valid, maxEntries, hits, misses, evictions and refusals; empty without a cluster.

With cache: that cache’s summary and a page of its entries, soonest deadline first, each with realm, key, valid, validUntil, remainingSeconds, basis and remaining, walked with page and per and answered in entriesPaging. An unknown name answers 200 with found: false and the names that exist.

KEYS ONLY: no cached value is in the reply, including for the caches that hold key material. THE FIGURES ARE THE ANSWERING PROCESS’S (pid), apart from otherProcesses, which carries sizes and counters only and never rows. A service operation: a realm’s own administrator is refused it.

Mirrors GET /admin/caches on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
cache query string   A cache name, to answer its entries rather than the list.
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 list, or one cache.

Member Type Required What it is
cache string   The one asked for by ?cache=.
caches list    
caches[].atBound boolean    
caches[].bound string    
caches[].counted boolean    
caches[].description string    
caches[].evictions integer    
caches[].expired integer    
caches[].hitMeaning string    
caches[].hitRatio number, or null    
caches[].hits integer, or null    
caches[].kind string    
caches[].largestRealm integer    
caches[].lifetime string    
caches[].maxEntries number, or null    
caches[].misses integer, or null    
caches[].name string    
caches[].notCountedWhy string    
caches[].owner string    
caches[].persisted boolean    
caches[].problem string, or null    
caches[].refusals integer    
caches[].scope string    
caches[].settings list    
caches[].settings[] string    
caches[].size integer    
caches[].title string    
caches[].valid integer    
entries list    
entries[].basis string    
entries[].key string    
entries[].realm string, or null    
entries[].remaining string    
entries[].remainingSeconds integer, or null    
entries[].valid boolean    
entries[].validUntil string, or null    
entriesPaging object   Which page of how many, and the query parameter that moves it.
entriesPaging.firstRow integer    
entriesPaging.lastRow integer    
entriesPaging.noun string    
entriesPaging.page integer    
entriesPaging.pages integer    
entriesPaging.param string    
entriesPaging.perPage integer    
entriesPaging.total integer    
found boolean    
generatedAt string    
known list   The caches there are, when the one asked for is not.
known[] string    
notListed list    
notListed[].what string    
notListed[].where string    
notListed[].why string    
otherProcesses list    
otherProcesses[].ageSeconds number    
otherProcesses[].caches list    
otherProcesses[].caches[].evictions integer    
otherProcesses[].caches[].hits integer, or null    
otherProcesses[].caches[].largestRealm integer    
otherProcesses[].caches[].maxEntries number, or null    
otherProcesses[].caches[].misses integer, or null    
otherProcesses[].caches[].name string    
otherProcesses[].caches[].refusals integer    
otherProcesses[].caches[].scope string    
otherProcesses[].caches[].size integer    
otherProcesses[].caches[].title string    
otherProcesses[].caches[].valid integer    
otherProcesses[].host string    
otherProcesses[].name string    
otherProcesses[].nodeId string    
otherProcesses[].pid string    
otherProcesses[].takenAt string    
otherProcesses[].thisNode boolean    
otherProcesses[].totals object    
otherProcesses[].totals.entries integer    
otherProcesses[].totals.evictions integer    
otherProcesses[].totals.refusals integer    
pid string    
summary object    
summary.atBound boolean    
summary.bound string    
summary.counted boolean    
summary.description string    
summary.evictions integer    
summary.expired integer    
summary.hitMeaning string    
summary.hitRatio number, or null    
summary.hits integer, or null    
summary.kind string    
summary.largestRealm integer    
summary.lifetime string    
summary.maxEntries number, or null    
summary.misses integer, or null    
summary.name string    
summary.notCountedWhy string    
summary.owner string    
summary.persisted boolean    
summary.problem string, or null    
summary.refusals integer    
summary.scope string    
summary.settings list    
summary.settings[] string    
summary.size integer    
summary.title string    
summary.valid integer    
totals object    
totals.caches integer    
totals.entries integer    
totals.expired integer    

GET /admin-api/cells

getCells

The cells of this service, the store’s tiers and the channel between cells

What this cell knows about the deployment (#98): multi (false in single-cell mode), cell, jurisdiction, peers (each id, jurisdiction, reachable and answeredMs or error — never an address), store (tiered, globalReplicaLagMs, the global change-log follower, the routing index’s counters and peoplePerCell), channel (the listener, this process’s certificate, the operations and the counters), placement (requests relayed and served here), sessions (projections held here and exports made from here) and settings.

Mirrors GET /admin/cells on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
people query string   A cell whose residents to list, under its release policy.
after query string   With people: the last name of the previous page.
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 cell map.

Member Type Required What it is
cell string    
channel object    
channel.certificateUntil string, or null    
channel.counters object    
channel.counters.failures integer    
channel.counters.opsIn integer    
channel.counters.opsOut integer    
channel.counters.refusedPeers integer    
channel.counters.relayedIn integer    
channel.counters.relayedOut integer    
channel.lastFailure string, or null    
channel.listenError string, or null    
channel.listening boolean    
channel.operations list    
channel.operations[] string    
channel.port integer, or null    
consoleUrl string, or null    
jurisdiction string, or null    
multi boolean    
peers list    
peers[].answeredMs number    
peers[].consoleUrl string    
peers[].error string    
peers[].id string    
peers[].jurisdiction string, or null    
peers[].reachable boolean    
peers[].reportedJurisdiction string, or null    
people object    
people.cell string    
people.next string   The after of the next page, empty on the last.
people.people list    
people.people[].displayName string    
people.people[].name string    
people.people[].uuid string    
people.refused string   Why the other cell did not list them.
placement object    
placement.placedHere integer    
placement.relayed integer    
placement.rows integer    
sessions object    
sessions.exports integer    
sessions.projections integer    
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
store object    
store.globalReplicaLagMs number, or null    
store.globalReplication object    
store.globalReplication.appliedSeq number    
store.globalReplication.byKind map   Rows applied, per kind of change.
store.globalReplication.byKind.{key} integer    
store.globalReplication.coordinating boolean    
store.globalReplication.failures integer    
store.globalReplication.highestSeq number    
store.globalReplication.holeRanges integer    
store.globalReplication.holes integer    
store.globalReplication.holesAbandoned integer    
store.globalReplication.lastError string, or null    
store.globalReplication.lastPullAt string, or null    
store.globalReplication.note string    
store.globalReplication.nudges integer    
store.globalReplication.originsDropped integer    
store.globalReplication.otherProcesses integer    
store.globalReplication.pollIntervalMs number    
store.globalReplication.pulls integer    
store.globalReplication.retention object    
store.globalReplication.retention.declaredGoneAt string, or null    
store.globalReplication.retention.fanInGraceS integer    
store.globalReplication.retention.lastTrim object    
store.globalReplication.retention.lastTrim.at string    
store.globalReplication.retention.lastTrim.bound number, or string, or null    
store.globalReplication.retention.lastTrim.error string, or null    
store.globalReplication.retention.lastTrim.readers integer    
store.globalReplication.retention.lastTrim.readersGone integer    
store.globalReplication.retention.lastTrim.trimmed integer    
store.globalReplication.retention.readerTtlS integer    
store.globalReplication.retention.reportError string, or null    
store.globalReplication.retention.reportedAt string, or null    
store.globalReplication.retention.retentionS integer    
store.globalReplication.retention.trimming boolean    
store.globalReplication.rowsApplied integer    
store.globalReplication.startedAt string, or null    
store.globalReplication.supported boolean    
store.peoplePerCell list    
store.peoplePerCell[].cell string    
store.peoplePerCell[].people integer    
store.peoplePerCell[].realm string    
store.routing object    
store.routing.conflicts integer    
store.routing.indexed integer    
store.routing.lastConflict string, or null    
store.routing.projectionWrites integer    
store.tiered boolean    

GET /admin-api/cells/people

getCellPeople

A page of another cell’s residents, where its release policy permits

Asks cell cell for a page of the people homed there in the realm of the call (#98 D11), after the login name after. The answering cell releases them only when its release policy permits its people to be listed from this cell’s jurisdiction; otherwise refused says why. Each person is name, uuid and displayName and nothing else.

Mirrors GET /admin/cells?people= on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
cell query string yes The other cell’s id.
after query string   The last login name of the previous page.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.

200: { cell, people, next } or { cell, refused }.

Member Type Required What it is
cell string    
next string   The after of the next page, empty on the last.
people list    
people[].displayName string    
people[].name string    
people[].uuid string    
refused string   Why the other cell did not list them.

POST /admin-api/cells/rehome

rehomePerson

Move a person homed in this cell to another cell

Re-homing (#98): everything the person holds is ended first — here and in every cell holding an export of their session — then their entry, devices and group memberships are sent to target with their entryUUID kept and their credentials sealed again under that cell’s key, the routing index is moved, and they are taken out of this cell. Call it at the cell that holds them (name it with ?cell= from anywhere). target must be in a jurisdiction the realm may place people in.

Mirrors POST /admin/cells (action=rehome) 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 (optional)

Member Type Required What it is
target string yes  
username string yes  

200: { ok: true, target }, or a refusal naming why.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
target string    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
target string    

GET /admin-api/crypto

getCryptoMetadata

Every algorithm this service signs, verifies and encrypts with

What this service does with cryptography, for every identity service it advertises: which digest, which signature algorithm, which cipher, which key, and which higher-level envelope each is wrapped in — JOSE, XMLDSIG and XML Encryption, WS-Security, COSE, X.509, Kerberos.

EVERY ALGORITHM LIST IN THE REPLY IS READ FROM THE MODULE THAT PERFORMS THE ALGORITHM, the way GET /admin/sts-metadata reads its endpoint list off the live express router — so it cannot claim something this service does not do, and it reports drift against that page’s own family list in both directions.

The postQuantum member is the one to read before quoting this reply: the signatures are partly post-quantum and the key establishment is entirely classical, and those are reported separately because a signature is checked when it is presented while captured ciphertext can be kept and opened later.

NOTHING HERE IS A SECRET: key types, key identifiers, curve names, certificate fingerprints and validity dates only, all of them already readable from /oauth2/jwks, /tls/server-certificate and the SPIFFE bundle endpoint. Nothing changes anything.

Mirrors GET /admin/crypto-metadata 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 whole report.

Member Type Required What it is
drift object    
drift.checked boolean    
drift.envelopes list    
drift.envelopes[] string    
drift.stale list    
drift.stale[] string    
drift.undescribed list    
drift.undescribed[] string    
encryption object    
encryption.jwe object    
encryption.jwe.contentEncryption list    
encryption.jwe.contentEncryption[].authenticated boolean    
encryption.jwe.contentEncryption[].bits number    
encryption.jwe.contentEncryption[].cekBytes number    
encryption.jwe.contentEncryption[].enc string    
encryption.jwe.contentEncryption[].mode string    
encryption.jwe.contentEncryption[].note string, or null    
encryption.jwe.keyManagementIn list    
encryption.jwe.keyManagementIn[] string    
encryption.jwe.keyManagementOut list    
encryption.jwe.keyManagementOut[] string    
encryption.kerberos object    
encryption.kerberos.decodeOnly list    
encryption.kerberos.decodeOnly[].id integer    
encryption.kerberos.decodeOnly[].name string    
encryption.kerberos.performed list    
encryption.kerberos.performed[].id integer    
encryption.kerberos.performed[].name string    
encryption.kerberos.preference list    
encryption.kerberos.preference[] integer    
encryption.tls object    
encryption.tls.sockets list    
encryption.tls.sockets[] string    
encryption.tls.what string    
encryption.xml object    
encryption.xml.blockCiphers list    
encryption.xml.blockCiphers[].authenticated boolean    
encryption.xml.blockCiphers[].ivBytes number    
encryption.xml.blockCiphers[].keyBits number    
encryption.xml.blockCiphers[].mode string    
encryption.xml.blockCiphers[].name string    
encryption.xml.blockCiphers[].uri string    
encryption.xml.configured object    
encryption.xml.configured.blockCipher string    
encryption.xml.configured.encryptAssertion boolean    
encryption.xml.configured.encryptLogoutNameId boolean    
encryption.xml.configured.keyTransport string    
encryption.xml.keyTransports list    
encryption.xml.keyTransports[].name string    
encryption.xml.keyTransports[].safe boolean    
encryption.xml.keyTransports[].scheme string    
encryption.xml.keyTransports[].uri string    
families list    
families[].algorithms list    
families[].algorithms[].how string    
families[].algorithms[].values list    
families[].algorithms[].values[] string, or number    
families[].algorithms[].what string    
families[].decrypts string    
families[].encrypts string    
families[].envelopes list    
families[].envelopes[] string    
families[].hashes string    
families[].keys string    
families[].name string    
families[].signs string    
families[].verifies string    
families[].whatItDoesNot string    
generatedAt string    
hashing object    
hashing.fixed list    
hashing.fixed[].hash string    
hashing.fixed[].what string    
hashing.fixed[].where string    
hashing.jws list    
hashing.jws[] string    
hashing.scimDigest list    
hashing.scimDigest[].hash string    
hashing.scimDigest[].token string    
hashing.weak list    
hashing.weak[].hash string    
hashing.weak[].where string    
hashing.weak[].why string    
hashing.xmlDigestMethods list    
hashing.xmlDigestMethods[].label string    
hashing.xmlDigestMethods[].uri string    
issuer string   This service as the request reached it.
keys object    
keys.bbs object    
keys.bbs.cryptosuite string    
keys.bbs.curve string    
keys.bbs.what string    
keys.curveKeys list    
keys.curveKeys[].alg string    
keys.curveKeys[].certificateFingerprint string, or null    
keys.curveKeys[].crv string    
keys.curveKeys[].kid string, or null    
keys.curveKeys[].kty string    
keys.postQuantum object    
keys.postQuantum.algorithms list    
keys.postQuantum.algorithms[] string    
keys.postQuantum.generated boolean    
keys.postQuantum.keys list    
keys.postQuantum.keys[].alg string    
keys.postQuantum.keys[].certificateFingerprint string, or null    
keys.postQuantum.keys[].kid string, or null    
keys.postQuantum.keys[].kty string    
keys.postQuantum.what string    
keys.realm string    
keys.regeneratedEveryStart boolean    
keys.signerGroups object    
keys.signerGroups.keys list    
keys.signerGroups.keys[].alg string    
keys.signerGroups.keys[].certificateFingerprint string, or null    
keys.signerGroups.keys[].group string    
keys.signerGroups.keys[].kid string, or null    
keys.signerGroups.keys[].kind string, or null    
keys.signerGroups.keys[].pairedSlot string, or null    
keys.signerGroups.keys[].slot string    
keys.signerGroups.model string    
keys.signing object    
keys.signing.alg string    
keys.signing.bits integer    
keys.signing.certificate string    
keys.signing.certificateFingerprint string, or null    
keys.signing.kid string    
keys.signing.kty string    
keys.signing.what string    
keys.spiffe object    
keys.spiffe.authorityFingerprint string, or null    
keys.spiffe.authorityKeyType string    
keys.spiffe.authoritySource string    
keys.spiffe.enabled boolean    
keys.spiffe.jwtAuthorities integer    
keys.spiffe.jwtKeyType string    
keys.spiffe.perRealm boolean    
keys.spiffe.ready boolean    
keys.spiffe.svidKeyType string    
keys.spiffe.trustAnchors integer    
keys.spiffe.trustDomain string, or null    
keys.spiffe.x509Authorities integer    
keys.spiffe.x509KeyType string    
keys.tls object    
keys.tls.certificates list    
keys.tls.certificates[].algorithm string, or null    
keys.tls.certificates[].certificateFingerprint string, or null    
keys.tls.fingerprint256 string, or null    
keys.tls.names list    
keys.tls.names[] string    
keys.tls.notAfter string, or null    
keys.tls.perRealm boolean    
keys.tls.subject string, or null    
keys.tls.what string    
oneModule string   Where all of this happens.
postQuantum object   The one to read before quoting this reply: signatures and key establishment are reported separately, because a signature is checked when it is presented while captured ciphertext can be kept and opened later.
postQuantum.algorithms object    
postQuantum.algorithms.composite list    
postQuantum.algorithms.composite[].alg string    
postQuantum.algorithms.composite[].domainSeparator string, or null    
postQuantum.algorithms.composite[].mlDsa string, or null    
postQuantum.algorithms.composite[].prehash string, or null    
postQuantum.algorithms.composite[].traditional string, or null    
postQuantum.algorithms.independence string    
postQuantum.algorithms.keyType string    
postQuantum.algorithms.mlDsa list    
postQuantum.algorithms.mlDsa[] string    
postQuantum.algorithms.slhDsa list    
postQuantum.algorithms.slhDsa[] string    
postQuantum.algorithms.what string    
postQuantum.keyEstablishment object    
postQuantum.keyEstablishment.drafts object    
postQuantum.keyEstablishment.drafts.hpke string    
postQuantum.keyEstablishment.drafts.hybrid string    
postQuantum.keyEstablishment.drafts.mlKem string    
postQuantum.keyEstablishment.hybrid list    
postQuantum.keyEstablishment.hybrid[] string    
postQuantum.keyEstablishment.mechanisms list    
postQuantum.keyEstablishment.mechanisms[] string    
postQuantum.keyEstablishment.postQuantum list    
postQuantum.keyEstablishment.postQuantum[] string    
postQuantum.keyEstablishment.state string    
postQuantum.keyEstablishment.surfaces list    
postQuantum.keyEstablishment.surfaces[].how string    
postQuantum.keyEstablishment.surfaces[].state string    
postQuantum.keyEstablishment.surfaces[].surface string    
postQuantum.keyEstablishment.what string    
postQuantum.keyEstablishment.whatWouldClose string    
postQuantum.signatures list    
postQuantum.signatures[].how string    
postQuantum.signatures[].state string    
postQuantum.signatures[].surface string    
postQuantum.symmetric object    
postQuantum.symmetric.state string    
postQuantum.symmetric.strongest string    
postQuantum.symmetric.what string    
realm string   The trust realm the key material below belongs to. The ALGORITHM tables are process-wide; the SIGNING KEYS are per realm.
signaturePolicy object    
signaturePolicy.pqcOnly boolean    
signaturePolicy.surfaces object    
signaturePolicy.surfaces.cose object    
signaturePolicy.surfaces.cose.acceptSetting string   The setting holding what this surface accepts.
signaturePolicy.surfaces.cose.rows list    
signaturePolicy.surfaces.cose.rows[].acceptRefusal string   Why not, or empty.
signaturePolicy.surfaces.cose.rows[].accepts boolean   Whether this realm accepts it now.
signaturePolicy.surfaces.cose.rows[].id string   The algorithm.
signaturePolicy.surfaces.cose.rows[].pqc string   pq or composite, or empty for a classical algorithm.
signaturePolicy.surfaces.cose.rows[].signRefusal string   Why not, or empty.
signaturePolicy.surfaces.cose.rows[].signs boolean   Whether this realm signs with it now.
signaturePolicy.surfaces.cose.rows[].spelling string   Its name on this surface.
signaturePolicy.surfaces.cose.rows[].weak boolean    
signaturePolicy.surfaces.cose.signSetting string   The setting holding what this surface signs with.
signaturePolicy.surfaces.di object    
signaturePolicy.surfaces.di.acceptSetting string   The setting holding what this surface accepts.
signaturePolicy.surfaces.di.rows list    
signaturePolicy.surfaces.di.rows[].acceptRefusal string   Why not, or empty.
signaturePolicy.surfaces.di.rows[].accepts boolean   Whether this realm accepts it now.
signaturePolicy.surfaces.di.rows[].id string   The algorithm.
signaturePolicy.surfaces.di.rows[].pqc string   pq or composite, or empty for a classical algorithm.
signaturePolicy.surfaces.di.rows[].signRefusal string   Why not, or empty.
signaturePolicy.surfaces.di.rows[].signs boolean   Whether this realm signs with it now.
signaturePolicy.surfaces.di.rows[].spelling string   Its name on this surface.
signaturePolicy.surfaces.di.rows[].weak boolean    
signaturePolicy.surfaces.di.signSetting string   The setting holding what this surface signs with.
signaturePolicy.surfaces.httpsig object    
signaturePolicy.surfaces.httpsig.acceptSetting string   The setting holding what this surface accepts.
signaturePolicy.surfaces.httpsig.rows list    
signaturePolicy.surfaces.httpsig.rows[].acceptRefusal string   Why not, or empty.
signaturePolicy.surfaces.httpsig.rows[].accepts boolean   Whether this realm accepts it now.
signaturePolicy.surfaces.httpsig.rows[].id string   The algorithm.
signaturePolicy.surfaces.httpsig.rows[].pqc string   pq or composite, or empty for a classical algorithm.
signaturePolicy.surfaces.httpsig.rows[].signRefusal string   Why not, or empty.
signaturePolicy.surfaces.httpsig.rows[].signs boolean   Whether this realm signs with it now.
signaturePolicy.surfaces.httpsig.rows[].spelling string   Its name on this surface.
signaturePolicy.surfaces.httpsig.rows[].weak boolean    
signaturePolicy.surfaces.httpsig.signSetting string   The setting holding what this surface signs with.
signaturePolicy.surfaces.jose object    
signaturePolicy.surfaces.jose.acceptSetting string   The setting holding what this surface accepts.
signaturePolicy.surfaces.jose.rows list    
signaturePolicy.surfaces.jose.rows[].acceptRefusal string   Why not, or empty.
signaturePolicy.surfaces.jose.rows[].accepts boolean   Whether this realm accepts it now.
signaturePolicy.surfaces.jose.rows[].id string   The algorithm.
signaturePolicy.surfaces.jose.rows[].pqc string   pq or composite, or empty for a classical algorithm.
signaturePolicy.surfaces.jose.rows[].signRefusal string   Why not, or empty.
signaturePolicy.surfaces.jose.rows[].signs boolean   Whether this realm signs with it now.
signaturePolicy.surfaces.jose.rows[].spelling string   Its name on this surface.
signaturePolicy.surfaces.jose.rows[].weak boolean    
signaturePolicy.surfaces.jose.signSetting string   The setting holding what this surface signs with.
signaturePolicy.surfaces.x509 object    
signaturePolicy.surfaces.x509.acceptSetting string   The setting holding what this surface accepts.
signaturePolicy.surfaces.x509.rows list    
signaturePolicy.surfaces.x509.rows[].acceptRefusal string   Why not, or empty.
signaturePolicy.surfaces.x509.rows[].accepts boolean   Whether this realm accepts it now.
signaturePolicy.surfaces.x509.rows[].id string   The algorithm.
signaturePolicy.surfaces.x509.rows[].pqc string   pq or composite, or empty for a classical algorithm.
signaturePolicy.surfaces.x509.rows[].signRefusal string   Why not, or empty.
signaturePolicy.surfaces.x509.rows[].signs boolean   Whether this realm signs with it now.
signaturePolicy.surfaces.x509.rows[].spelling string   Its name on this surface.
signaturePolicy.surfaces.x509.rows[].weak boolean    
signaturePolicy.surfaces.x509.signSetting string   The setting holding what this surface signs with.
signaturePolicy.surfaces.xml object    
signaturePolicy.surfaces.xml.acceptSetting string   The setting holding what this surface accepts.
signaturePolicy.surfaces.xml.rows list    
signaturePolicy.surfaces.xml.rows[].acceptRefusal string   Why not, or empty.
signaturePolicy.surfaces.xml.rows[].accepts boolean   Whether this realm accepts it now.
signaturePolicy.surfaces.xml.rows[].id string   The algorithm.
signaturePolicy.surfaces.xml.rows[].pqc string   pq or composite, or empty for a classical algorithm.
signaturePolicy.surfaces.xml.rows[].signRefusal string   Why not, or empty.
signaturePolicy.surfaces.xml.rows[].signs boolean   Whether this realm signs with it now.
signaturePolicy.surfaces.xml.rows[].spelling string   Its name on this surface.
signaturePolicy.surfaces.xml.rows[].weak boolean    
signaturePolicy.surfaces.xml.signSetting string   The setting holding what this surface signs with.
signatures object    
signatures.canonicalization list    
signatures.canonicalization[].comments boolean, or null    
signatures.canonicalization[].exclusive boolean, or null    
signatures.canonicalization[].label string    
signatures.canonicalization[].uri string    
signatures.canonicalization[].usedHere boolean, or null    
signatures.cose list    
signatures.cose[].coseAlg integer    
signatures.cose[].jose string    
signatures.jws list    
signatures.jws[].alg string    
signatures.jws[].asymmetric boolean    
signatures.jws[].composite boolean    
signatures.jws[].crv string    
signatures.jws[].dpop boolean    
signatures.jws[].family string, or null    
signatures.jws[].hash string    
signatures.jws[].kty string    
signatures.jws[].postQuantum boolean    
signatures.other list    
signatures.other[].name string    
signatures.other[].what string    
signatures.xml list    
signatures.xml[].family string, or null    
signatures.xml[].hash string, or null    
signatures.xml[].keyKind string, or null    
signatures.xml[].label string    
signatures.xml[].signsWith boolean    
signatures.xml[].uri string    
signatures.xml[].verifiedHere boolean    
standards list    
standards[].coverage string    
standards[].key string    
standards[].name string    
standards[].specs list    
standards[].specs[] string    
standards[].what string    

GET /admin-api/database

getDatabase

Everything PostgreSQL reports about itself, and this service’s schema in it

Twenty probes against PostgreSQL’s catalog views, each run, timed and caught SEPARATELY: the server and its uptime, the database size, every counter in pg_stat_database, the backends and locks, the background writer, the checkpointer, the write-ahead log and the archiver, then per-table and per-index statistics, sizes, columns and constraints for the schema this service owns.

THE COLUMNS ARE THE SERVER’S AND NOT THIS API’S. Every statement is a SELECT *, because PostgreSQL moves these views between major versions — pg_stat_bgwriter has eleven columns on 16 and four on 17 and later, when the checkpoint counters moved to a view that does not exist before 17. So a client reading a named column must treat its absence as ordinary rather than as an error, and the reply is the right place to learn what this server actually has.

A PROBE THAT FAILED IS A MEMBER AND NOT AN ABSENCE: probes.<id>.ok is false and code carries PostgreSQL’s SQLSTATE, because 42P01 (no such relation — an older server) and 42501 (insufficient privilege — this service does not hold pg_monitor) are completely different things to do something about. failed lists them.

derived carries four RATIOS PostgreSQL deliberately does not keep — cache hit, rollback share, dead-tuple share, and indexes nothing has ever scanned — all of them cumulative since stats_reset, which is in the reply beside them. schemaDrift is the one ASSERTION here rather than a measurement: the objects the driver declares against the ones the server actually has, a check nothing else in this service makes.

IT ANSWERS 200 WITH available: false WHEN THERE IS NO DATABASE, which is the ordinary case: persistence.mode defaults to memory. That is not an error — the question was answerable and the answer is that there is nothing to report — and why says which of three reasons it is.

NOTHING HERE CHANGES ANYTHING and no connection string is in the reply: target names the host, port, database and user, parsed by the one function in this service that already does that without printing the password.

Mirrors GET /admin/database 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 whole report.

Member Type Required What it is
available boolean    
derived object    
derived.cacheHitPercent number, or null    
derived.deadTuplePercent number, or null    
derived.idxScans number    
derived.rollbackPercent number, or null    
derived.seqScans number    
derived.statsReset string, or null    
derived.unusedIndexes list    
derived.unusedIndexes[] string    
error string    
failed list    
failed[] string    
mode string    
ok boolean    
pool object    
pool.idle number    
pool.max number    
pool.total number    
pool.waiting number    
probes map   One answer per probe, by its id.
probes.{key}.code string, or number    
probes.{key}.count integer    
probes.{key}.error string    
probes.{key}.expected string, or number, or boolean, or null    
probes.{key}.group string    
probes.{key}.ok boolean    
probes.{key}.row any JSON   The rows of a PostgreSQL or MariaDB statistics view, keyed by the engine’s own column names and typed by its driver, which vary by engine and version. The rows of a PostgreSQL or MariaDB statistics view, keyed by the engine’s own column names and typed by its driver, which vary by engine and version.
probes.{key}.rows any JSON   The rows of a PostgreSQL or MariaDB statistics view, keyed by the engine’s own column names and typed by its driver, which vary by engine and version. The rows of a PostgreSQL or MariaDB statistics view, keyed by the engine’s own column names and typed by its driver, which vary by engine and version.
probes.{key}.shape string    
probes.{key}.tookMs number    
probes.{key}.what string    
schema string, or null    
schemaDrift object    
schemaDrift.declared list    
schemaDrift.declared[] string    
schemaDrift.missing list    
schemaDrift.missing[] string    
schemaDrift.present list    
schemaDrift.present[] string    
schemaExpected object    
schemaExpected.version string, or number, or boolean, or null    
statementTimeoutMs number    
statementTimeoutSet boolean    
target object   Parsed out of the connection string, which is never returned.
target.caFile string, or null    
target.database string, or null    
target.encrypted boolean    
target.host string, or null    
target.note string    
target.passwordFrom string    
target.passwordProvider string    
target.passwordSecret object    
target.passwordSecret.configured boolean    
target.passwordSecret.field string    
target.passwordSecret.known boolean    
target.passwordSecret.label string    
target.passwordSecret.provider string    
target.passwordSecret.providers list    
target.passwordSecret.providers[].id string    
target.passwordSecret.providers[].label string    
target.passwordSecret.secret string    
target.passwordSecret.shared boolean    
target.passwordSecret.where object    
target.passwordSecret.where.authenticates string    
target.passwordSecret.where.endpoint string    
target.passwordSecret.where.field string    
target.passwordSecret.where.from string    
target.passwordSecret.where.region string    
target.passwordSecret.where.shared boolean    
target.passwordSecret.where.vault string    
target.passwordSecret.where.wraps string    
target.port string, or null    
target.sslmode string    
target.tls string    
target.user string, or null    
target.verifyCertificate boolean    
tookMs number    
what string    
why string    

GET /admin-api/debugger

getDebugger

Whether the identity protocol debugger is embedded, where it answers, and what its api process is doing

The embedded identity protocol debugger: embedded and the setting and mode that decided it, the listener’s port and whether it is listening, the client (clientId), the resource server (resource), the permission its api requires (permission) and the audience a token for it carries (audience), and under api the child process: its state (starting, running, restarting, given-up, not-installed, stopped), process id, socket, starts, consecutive failures, last exit and last error, and — in product mode — the allowedRanges it may dial. settings is the Protocol debugger group as /admin/debugger draws it.

Nothing here opens the debugger: its gate is the permission, which the authorization server issues to console administrators only.

Mirrors GET /admin/debugger 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 debugger report.

Member Type Required What it is
api object    
api.allowList boolean    
api.allowListProblems list    
api.allowListProblems[] string    
api.allowedRanges list    
api.allowedRanges[] string    
api.anchorReplacements integer    
api.apiDirectory string, or null    
api.consecutiveFailures integer    
api.lastError string, or null    
api.lastExit object    
api.lastExit.at string    
api.lastExit.code integer, or null    
api.lastExit.signal string, or null    
api.lastExit.upSeconds number    
api.listeningAt string, or null    
api.pid integer, or null    
api.socket string, or null    
api.startedAt string, or null    
api.starts integer    
api.state string    
api.uiUrl string, or null    
audience string    
clientId string    
embedded boolean    
listenError string, or null    
listening boolean    
mode string    
permission string    
port number    
publicBaseUrl string, or null    
resource string    
scheme string    
setting string    
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
startProblem string, or null    
started boolean    
uiDirectory string, or null    

GET /admin-api/encryption

getEncryption

What this service encrypts at rest, and how much of it it has done

The at-rest half of this service’s cryptography: which data is sealed, where it lives, under which key and which algorithm, and how many encryptions and decryptions have happened in this process.

IT IS NOT GET /admin-api/crypto WITH FEWER FIELDS. That one answers what this service DOES when it signs or encrypts — per protocol family, read out of the module that performs each algorithm — and reads identically on a service that started a second ago. This one is TRAFFIC: accounting goes up while something is happening, counted at the one funnel both operations pass through rather than at the call sites, because a total assembled from call sites is wrong the first time somebody adds another one and is wrong silently.

classes LISTS WHAT IS DELIBERATELY NOT SEALED BESIDE WHAT IS, each with the reason — passwords are hashed rather than encrypted, which is stronger; the post-quantum keys, the TLS certificate and the SPIFFE authorities are not persisted at all, so there is nothing at rest to seal. A list of only the yeses would answer “is X encrypted” by silence.

THE COUNTERS ARE PROCESS-WIDE AND NOT PER REALM — a key-encryption key belongs to the process — and they are in memory, so a restart is how you get an empty one. Under workers.requestCount each request worker keeps its own, so a dispatched service answers this from whichever worker took the call.

NO CIPHERTEXT AND NO PLAINTEXT IS IN THE REPLY, and there is no operation anywhere that opens a sealed value on request: a sealed value is a private key, an authenticator’s shared secret or somebody’s recovery codes. key.where names the PROVIDER the key-encryption key is read from and never the key.

boundaries IS THE PART TO READ BEFORE ACTING ON THE REST, and it is in this reply rather than in a document because a machine reader has no page to have read it on. Two limits and one deployment mistake: there is ONE key-encryption key for the service and NOT one per trust realm (perRealmKey: false) — it wraps every realm’s data encryption keys, one per realm per class — so a realm is not an independent boundary at rest and rotating the key re-wraps every realm’s data keys; everything NOT in classes is plaintext in the store, because the layer that covers a whole database belongs under it rather than inside it (a column-level answer leaves plaintext in the WAL, in spilled sorts, in a pg_dump, on replicas and in query logs) — that layer is the operator’s and docs/encryption-at-rest.md is the write-up; and the key must not live on the volume it protects, which is what the file provider invites and why every other provider exists.

Mirrors GET /admin/encryption on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
dataKeysPage query integer   Which page of dataKeys.keys to return, clamped as every page is; dataKeys.paging says which page it 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 whole report.

Member Type Required What it is
accounting object    
accounting.ciphertextBytes number    
accounting.decryptions integer    
accounting.encryptions integer    
accounting.failures integer    
accounting.firstAt string, or null    
accounting.labels list    
accounting.labels[].ciphertextBytes number    
accounting.labels[].decryptions integer    
accounting.labels[].encryptions integer    
accounting.labels[].failures integer    
accounting.labels[].firstAt number   Milliseconds, 0 when never.
accounting.labels[].label string    
accounting.labels[].lastAt number   Milliseconds, 0 when never.
accounting.labels[].plaintextBytes number    
accounting.lastAt string, or null    
accounting.operations integer    
accounting.plaintextBytes number    
accounting.since string    
accountingNote string    
algorithm object    
algorithm.aad string    
algorithm.cipher string    
algorithm.dataCiphers list    
algorithm.dataCiphers[] string    
algorithm.dataKeys string    
algorithm.dekWrap string    
algorithm.envelope string    
algorithm.ivBits integer    
algorithm.keyBits integer    
algorithm.perRecordSubkey boolean    
algorithm.tagBits integer    
algorithm.version string, or number    
algorithmNote string    
boundaries object    
boundaries.keyResidency string    
boundaries.perRealmDataKey boolean    
boundaries.perRealmKey boolean    
boundaries.realms string    
boundaries.storage string    
classes list    
classes[].decryptions integer, or null    
classes[].encryptions integer, or null    
classes[].failures integer, or null    
classes[].label string, or null    
classes[].lastAt string, or null    
classes[].sealed boolean    
classes[].what string    
classes[].where string    
classes[].why string    
dataKeys object    
dataKeys.counts object    
dataKeys.counts.current integer    
dataKeys.counts.derived integer    
dataKeys.counts.destroyed integer    
dataKeys.counts.pending integer    
dataKeys.counts.superseded integer    
dataKeys.keys list    
dataKeys.keys[].activateAt string, or null    
dataKeys.keys[].ageDays integer, or null    
dataKeys.keys[].alg string    
dataKeys.keys[].cls string, or null    
dataKeys.keys[].countedAt string, or null    
dataKeys.keys[].createdAt string, or null    
dataKeys.keys[].id string    
dataKeys.keys[].realm string, or null    
dataKeys.keys[].scope string, or null    
dataKeys.keys[].state string    
dataKeys.keys[].values number, or null    
dataKeys.lastCounted string, or null    
dataKeys.lifecycle object    
dataKeys.lifecycle.activationLeadSeconds number    
dataKeys.lifecycle.countOffReason string    
dataKeys.lifecycle.counting boolean    
dataKeys.lifecycle.directoryCipher string    
dataKeys.lifecycle.jobs list    
dataKeys.lifecycle.jobs[] string    
dataKeys.lifecycle.kekRotation boolean    
dataKeys.lifecycle.kekRotationOffReason string    
dataKeys.lifecycle.offReason string    
dataKeys.lifecycle.on boolean    
dataKeys.lifecycle.retireAfterDays number    
dataKeys.lifecycle.rotationDays number    
dataKeys.lifecycle.scheduleOffReason string    
dataKeys.lifecycle.scheduled boolean    
dataKeys.note string    
dataKeys.paging object   Which page of how many, and the query parameter that moves it.
dataKeys.paging.firstRow integer    
dataKeys.paging.lastRow integer    
dataKeys.paging.noun string    
dataKeys.paging.page integer    
dataKeys.paging.pages integer    
dataKeys.paging.param string    
dataKeys.paging.perPage integer    
dataKeys.paging.total integer    
dataKeys.total integer    
failuresNote string    
key object    
key.ephemeral boolean    
key.inKms boolean    
key.kmsKey string, or null    
key.note string    
key.persists boolean    
key.present boolean    
key.provider string    
key.providerKnown boolean    
key.providerLabel string    
key.providers list    
key.providers[].id string    
key.providers[].label string    
key.where object    
key.where.authenticates string    
key.where.endpoint string    
key.where.field string    
key.where.from string    
key.where.region string    
key.where.shared boolean    
key.where.vault string    
key.where.wraps string    
mode string    
noSamples string    
store object    
store.configuredMode string    
store.fellBack boolean    
store.mode string    
store.note string    
store.persistsMinted boolean    
unclassified list    
unclassified[].ciphertextBytes number    
unclassified[].decryptions integer    
unclassified[].encryptions integer    
unclassified[].failures integer    
unclassified[].firstAt number   Milliseconds, 0 when never.
unclassified[].label string    
unclassified[].lastAt number   Milliseconds, 0 when never.
unclassified[].plaintextBytes number    
what string    

POST /admin-api/encryption/count-data-keys

countDataKeys

Count what is sealed under every data key now

Queues a run of keys.data-key-count and answers 202: the values sealed under every data encryption key are counted in one pass of the store and kept on each key, where GET /admin-api/encryption reports them as values and countedAt (#391). 400 (STS-KEYS-0100) where data keys are not stored or the store cannot count (only PostgreSQL can).

Mirrors POST /admin/encryption/data-keys 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 (optional)

An empty object.

200: The queued run, as for rotate-data-keys.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

202: The answer.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

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

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

POST /admin-api/encryption/reencrypt-data-keys

reencryptDataKeys

Run the data re-encryption pass now

Queues a run of keys.data-key-reencrypt and answers 202: what is still sealed under a superseded data encryption key is re-sealed under the current one, and a superseded key nothing is sealed under any longer, superseded for keys.dataKeyRetireAfterDays, is destroyed. 400 (STS-KEYS-0100) where data keys are not stored.

Mirrors POST /admin/encryption/data-keys 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 (optional)

An empty object.

200: The queued run, as for rotate-data-keys.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

202: The answer.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

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

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

POST /admin-api/encryption/rotate-data-keys

rotateDataKeys

Rotate the data encryption keys now

Queues a run of the scheduler job keys.data-key-rotate-now and answers 202 with its runId. Every stored data encryption key — or one realm’s, or one class’s — gets a successor, used keys.dataKeyActivationLeadSeconds after it is published; what the old key sealed is re-sealed by keys.data-key-reencrypt. 400 (STS-KEYS-0100) where data keys are derived per run and not stored, or where none serves the realm or class.

Mirrors POST /admin/encryption/data-keys 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 (optional)

Member Type Required What it is
cls string   A data class, e.g. minted-rows; omitted for every class.
realm string   A realm id; omitted for every realm, default for the default realm.

200: The queued run: runId, message, and run, the address to follow it at.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

202: The answer.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

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

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

POST /admin-api/encryption/rotate-kek

rotateKek

Rotate the key-encryption key in its key management service

Queues a run of keys.kek-rotate-now and answers 202: the key management service makes a new version of the key-encryption key (Transit, Cloud KMS and Key Vault; AWS KMS rotates on demand behind the same key id) and every data encryption key is re-wrapped under it. The run fails (STS-KEYS-0105) where the identity this service runs as may use the key but not rotate it. 400 (STS-KEYS-0104) where the key is read into the process: its successor is configured with keys.previousKek* and a restart.

Mirrors POST /admin/encryption/data-keys 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 (optional)

An empty object.

200: The queued run, as for rotate-data-keys.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

202: The answer.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

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

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

GET /admin-api/keys

getKeys

Every key pair this process generated at start, and what it is for

A LIST and never key material. The signing keys are per trust realm and the TLS certificate belongs to the process, and each row says which. formats is what that key can be exported as, computed rather than listed: a key with no certificate cannot be a PKCS#12, and a post-quantum key has no PKCS#8 encoding at all, so the answer differs per key for two different reasons.

Nothing here is key material. POST /admin-api/keys/export is the operation that hands one over.

Mirrors GET /admin/keys 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 key pairs.

Member Type Required What it is
formats list   Every format the exporter knows. What a PARTICULAR key offers is its own formats.
formats[] string    
issuer string    
keys list    
keys[] object   One key pair.
keys[].alg string    
keys[].bits number    
keys[].certifiedBy object    
keys[].certifiedBy.issuedBy string, or null    
keys[].certifiedBy.notAfter string, or null    
keys[].certifiedBy.pinned boolean    
keys[].certifiedBy.subject string, or null    
keys[].crv string    
keys[].fingerprint string, or null    
keys[].formats list   Empty means not exportable.
keys[].formats[] string    
keys[].generated boolean    
keys[].hasCertificate boolean   Whether a PKCS#12 is possible.
keys[].id string   What POST /admin-api/keys/export takes as key.
keys[].kid string   Empty for the TLS key, which has a fingerprint instead.
keys[].kty string, or null    
keys[].label string    
keys[].names list    
keys[].names[] string    
keys[].notAfter string, or null    
keys[].pqc object    
keys[].pqc.algorithm string    
keys[].pqc.family string    
keys[].pqc.kind string    
keys[].pqc.label string    
keys[].pqc.standard string    
keys[].realm string    
keys[].scope string   realm or process.
keys[].subject string, or null    
keys[].usedFor list    
keys[].usedFor[] string    
realm string   The signing keys belong to this realm; the TLS key to the process.
regeneratedEveryStart boolean    
residency object    
residency.note string    
residency.persisting boolean    
residency.plaintextHeld list    
residency.plaintextHeld[] string    
residency.plaintextTtlS number    
residency.realmsHeld list    
residency.realmsHeld[] string    
residency.retention string    
rotation object    
rotation.offReason string    
rotation.refresh object    
rotation.refresh.graceDays number    
rotation.refresh.lastRotated string, or null    
rotation.refresh.retired integer    
rotation.scheduled boolean    
rotation.units list    
rotation.units[].credentialSigner boolean    
rotation.units[].current string, or null    
rotation.units[].graceDays number    
rotation.units[].intervalDays number    
rotation.units[].lastRotated string, or null    
rotation.units[].next object    
rotation.units[].next.kid string    
rotation.units[].next.since string, or null    
rotation.units[].retired list    
rotation.units[].retired[].kid string    
rotation.units[].retired[].retiredAt string, or null    
rotation.units[].retired[].verifiesUntil string, or null    
rotation.units[].unit string    
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
verifiesCredentials boolean    
warning string    

POST /admin-api/keys/emergency

rotateSigningKeysEmergency

Rotate the realm’s signing keys in an EMERGENCY

For keys presumed compromised. Queues signing.rotate-now with the emergency flag and answers 202: every key of every named unit (or all) is replaced with a NEW key — not the published next one — with no grace; their certificates are revoked for keyCompromise; the refresh-token keys are replaced; and every session of the realm is ended, with CAEP session-revoked and RISC sessions-revoked. Everything signed before it stops verifying at once. confirm must be compromised (STS-KEYS-0066 otherwise).

Mirrors POST /admin/keys/export and POST /admin/keys/rotate 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
confirm one of compromised yes  
units list    
units[] string    

200: The queued run, as for rotate.

Member Type Required What it is
accepted boolean    
emergency boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    
units list    
units[] string    

202: The answer.

Member Type Required What it is
accepted boolean    
emergency boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    
units list    
units[] string    

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

Member Type Required What it is
accepted boolean    
emergency boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    
units list    
units[] string    

POST /admin-api/keys/export

exportKey

Hand over one key pair, in a chosen keystore format

THIS OPERATION RETURNS PRIVATE KEY MATERIAL. It is the API half of the one page in this console where reading is taking.

It is defensible because of what these keys are in development mode: generated at start, held only in memory, dead when the process exits, and protecting nothing — this service checks no password and validates no token it did not mint. In product mode the signing keys are kept in the persistence store, and this operation hands over one that outlives the call. It needs an access token carrying admin:write (unless adminApi.authRequired is off, when anybody who can reach this port can call it), like every other write here — stated again because this one returns a key.

format is one of pem, der, jwk or pkcs12. A password is REQUIRED for pkcs12 and optional for the rest, where it encrypts the private half. The reply carries the file base64-encoded rather than raw, because this API answers JSON everywhere else and a caller that suddenly got octets would have to special-case one operation.

Mirrors POST /admin/keys/export and POST /admin/keys/rotate 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
format one of pem, der, jwk, pkcs12 yes PKCS#12 is offered only for a key this service holds a certificate for — the signing key and the TLS key.
key string yes The id from GET /admin-api/keys.
password string   REQUIRED for pkcs12; optional for the other three, where it encrypts the private half. Empty means the private key comes out in the clear.

200: The exported files.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
files list    
files[] object   One file.
files[].base64 string    
files[].bytes integer    
files[].mime string    
files[].name string    
message string    
ok boolean yes  
publicOnly boolean   True for a post-quantum key, which comes out as its public half.
status string   One line about what came out.

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

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/keys/history

getKeyHistory

Every signing key this realm has ever held

THE RECORD THAT OUTLIVES THE KEY (#42’s follow-up). A retired signing key is DROPPED once it passes its grace and its private half is gone — this is what survives: when each key of each unit was minted, promoted, retired and dropped, why, and the certificate that vouched for it, with its serial, subject and validity window. Nothing here is key material, and nothing here can produce a signature.

With no unit the answer is the index of units and their counts; with one it is that unit’s generations, newest first and PAGED (page, per). The history is derived from the realm’s key set, so this read also OBSERVES — idempotent, so in the steady state it writes nothing.

Mirrors GET /admin/keys/history on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
unit query string   One signing unit (jose:RS256, xml:RS256, jose:ES256:P-256, bbs:BBS, …). Omitted, the answer is the index of units and their counts.
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 units, and one unit’s generations.

Member Type Required What it is
found boolean    
observed boolean    
paging object   Which page of how many, and the query parameter that moves it.
paging.firstRow integer    
paging.lastRow integer    
paging.noun string    
paging.page integer    
paging.pages integer    
paging.param string    
paging.perPage integer    
paging.total integer    
realm string    
rows list    
rows[].alg string, or null    
rows[].certificate object    
rows[].certificate.certificatePem string    
rows[].certificate.chainPem list    
rows[].certificate.chainPem[] string    
rows[].certificate.keyAlg string    
rows[].certificate.notAfter string    
rows[].certificate.notBefore string    
rows[].certificate.serialHex string    
rows[].certificate.signatureAlg string    
rows[].certificate.subject string    
rows[].certificate.thumbprint string    
rows[].createdAt string, or null    
rows[].crv string    
rows[].droppedAt string, or null    
rows[].firstSeenAt string, or null    
rows[].kid string    
rows[].kind string, or null    
rows[].promotedAt string, or null    
rows[].reason string    
rows[].retiredAt string, or null    
rows[].role string, or null    
rows[].slot string, or null    
rows[].unit string    
rows[].useCase string, or null    
rows[].verifiesUntil string, or null    
total integer    
unit string    
units list    
units[].alg string, or null    
units[].dropped integer    
units[].generations integer    
units[].live integer    
units[].newestAt number    
units[].slot string, or null    
units[].unit string    
units[].useCase string, or null    
units[].withCertificate integer    

400: The answer.

Member Type Required What it is
errors list    
errors[] string    
ok boolean    
units list   The units there are.
units[] string    

GET /admin-api/keys/history/certificate

getKeyHistoryCertificate

One signing key’s certificate chain, as PEM

The certificate a signing key was published with, and the chain to the realm’s root, leaf first — a public document, and the half of a retired key worth keeping. Named by unit and kid, as GET /admin-api/keys/history lists them (#446: it was /admin/keys/history/certificate).

Mirrors GET /admin/keys/history on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
unit query string yes The signing unit, jose:RS256 and the like.
kid query string yes The key’s identifier.
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 chain, as application/pem-certificate-chain.

As application/pem-certificate-chain.

POST /admin-api/keys/rotate

rotateSigningKeys

Rotate the realm’s signing keys now

Queues a run of the scheduler job signing.rotate-now and answers 202 with its runId (follow it at /admin-api/scheduler?run=). Each named unit — or every unit and the refresh-token keys, for units empty or "all" — has its next key promoted; the key it replaces goes on verifying through its grace. An unknown unit is 400 (STS-KEYS-0065).

Mirrors POST /admin/keys/export and POST /admin/keys/rotate 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 (optional)

Member Type Required What it is
units list   Units from GET /admin-api/keys rotation.units, e.g. jose:RS256.
units[] string    

200: The queued run: runId, units, and run, the address to follow it at.

Member Type Required What it is
accepted boolean    
emergency boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    
units list    
units[] string    

202: The answer.

Member Type Required What it is
accepted boolean    
emergency boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    
units list    
units[] string    

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

Member Type Required What it is
accepted boolean    
emergency boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    
units list    
units[] string    

GET /admin-api/listeners

getListeners

Every listener, its TLS policy and client authentication, and which hosted application is on which

For the realm the call is in: realm; listeners, the built-in ones (each id, name, setting, port, tls, what, policy and http); custom, the custom listeners this realm sees — the service’s (listeners.custom) and its own (listeners.realm), every realm’s in the default realm — each with id, owner, port, publicBaseUrl, hostnames, clientAuth, certificateSource, its state on this node, certificate, policy and http; applications, each hosted application with the listeners it is on, the advertised one its URLs are built on and what decidedBy (realm, service or default); definitions, the JSON the two writes take; rescue (listeners.adminOnMain); problem and warnings; the process’s process policy and the TLS listeners live on this node. A policy is minVersion, tls12, tls13Suites (each name and postQuantum, in order), tls12Ciphers, pqcOnly, groups and clientAuth (none, optional, required, or the protocol’s rule). An http is the HTTP listener’s pooling in force, or null: keepAliveTimeoutS, headersTimeoutS, maxRequestsPerSocket, maxConnections, http2 (whether h2 is offered) and http2MaxConcurrentStreams (the streams one HTTP/2 connection may have open at once).

Mirrors GET /admin/listeners 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 listeners view.

Member Type Required What it is
applications list    
applications[].advertised string, or null    
applications[].application string    
applications[].decidedBy string    
applications[].label string    
applications[].listeners list    
applications[].listeners[] string    
applications[].session boolean    
applications[].what string    
custom list    
custom[].certificate object    
custom[].certificate.notAfter string    
custom[].certificate.notBefore string    
custom[].certificate.serialHex string    
custom[].certificate.source string    
custom[].certificateSource string    
custom[].clientAuth string, or null    
custom[].hostnames list    
custom[].hostnames[] string    
custom[].http object    
custom[].http.headersTimeoutS number    
custom[].http.http2 boolean    
custom[].http.http2MaxConcurrentStreams number    
custom[].http.keepAliveTimeoutS number    
custom[].http.maxConnections number    
custom[].http.maxRequestsPerSocket number    
custom[].id string    
custom[].label string, or null    
custom[].owner string    
custom[].policy object    
custom[].policy.clientAuth string, or null    
custom[].policy.groups string    
custom[].policy.minVersion string, or null    
custom[].policy.pqcOnly boolean    
custom[].policy.sessionCacheSize number    
custom[].policy.sessionTimeoutS number    
custom[].policy.signatureAlgorithms string    
custom[].policy.tls12 boolean    
custom[].policy.tls12Ciphers list    
custom[].policy.tls12Ciphers[] string    
custom[].policy.tls13Suites list    
custom[].policy.tls13Suites[].name string    
custom[].policy.tls13Suites[].postQuantum boolean    
custom[].policy.truststore string    
custom[].port integer    
custom[].publicBaseUrl string, or null    
custom[].state string    
custom[].tls map   A listener’s own TLS values, per setting.
custom[].tls.{key} list, or string, or number, or boolean, or null    
custom[].tls.{key}[] string, or number, or boolean    
custom[].why string, or null    
definitions object    
definitions.applications string    
definitions.cookieDomain string    
definitions.listeners string    
definitions.serviceApplications string    
listeners list    
listeners[].group string, or null    
listeners[].http object    
listeners[].http.headersTimeoutS number    
listeners[].http.http2 boolean    
listeners[].http.http2MaxConcurrentStreams number    
listeners[].http.keepAliveTimeoutS number    
listeners[].http.maxConnections number    
listeners[].http.maxRequestsPerSocket number    
listeners[].id string    
listeners[].name string    
listeners[].policy object    
listeners[].policy.clientAuth string, or null    
listeners[].policy.groups string    
listeners[].policy.minVersion string, or null    
listeners[].policy.pqcOnly boolean    
listeners[].policy.sessionCacheSize number    
listeners[].policy.sessionTimeoutS number    
listeners[].policy.signatureAlgorithms string    
listeners[].policy.tls12 boolean    
listeners[].policy.tls12Ciphers list    
listeners[].policy.tls12Ciphers[] string    
listeners[].policy.tls13Suites list    
listeners[].policy.tls13Suites[].name string    
listeners[].policy.tls13Suites[].postQuantum boolean    
listeners[].policy.truststore string    
listeners[].port string, or number, or boolean, or null    
listeners[].setting string    
listeners[].tls boolean    
listeners[].what string    
live list    
live[].kind string    
live[].label string    
live[].realm string, or null    
problem object    
problem.code string    
problem.message string    
process object    
process.clientAuth string, or null    
process.groups string    
process.minVersion string, or null    
process.pqcOnly boolean    
process.sessionCacheSize number    
process.sessionTimeoutS number    
process.signatureAlgorithms string    
process.tls12 boolean    
process.tls12Ciphers list    
process.tls12Ciphers[] string    
process.tls13Suites list    
process.tls13Suites[].name string    
process.tls13Suites[].postQuantum boolean    
process.truststore string    
realm string    
rescue boolean    
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
warnings list    
warnings[] string    

POST /admin-api/listeners/set-applications

setListenerApplications

Map hosted applications to listeners

Replaces listeners.applications in the realm the call is in — the service’s mapping in the default realm, the realm’s own entries (read before the service’s) in any other. value is a JSON object from an application id, or *, to { listeners, advertised }, and empty for none. A path of an application is answered only on the listeners it is on (404, STS-TLS-0047, elsewhere), and its URLs are built on the advertised one — CHANGING WHERE oauth-oidc IS ADVERTISED CHANGES ITS ISSUER. A mapping that takes management-api off the listener this call arrived on is refused (STS-CORE-0156) unless confirm is true.

Mirrors POST /admin/listeners 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
confirm boolean, or one of true, false, on   Take the management API off the listener this call arrived on.
value string, or object yes The mapping: a JSON object, as text or as the object.

200: That it is set.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
realm string, or null    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
realm string, or null    

POST /admin-api/listeners/set-listeners

setListeners

Replace the custom listeners this realm defines

In the default realm, the service’s listeners (listeners.custom), which answer every realm; in any other, the realm’s own (listeners.realm), which answer that realm alone. value is a JSON array of { id, port, publicBaseUrl, hostnames, certificateFile, privateKeyFile, clientAuth, tls } — or the array itself — and empty for none. Every node binds, rebinds or closes each listener at once; a change of clientAuth or tls is applied at the next handshake without a rebind. Refused when it would remove a listener a mapping names, reuse a port, or split the sign-on session’s applications across host names its cookie cannot reach (STS-CORE-0145 to 0155).

Mirrors POST /admin/listeners 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
value list, or string yes  
value[] any JSON    

200: That it is set.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
realm string, or null    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
realm string, or null    

GET /admin-api/mail

getMail

The mail channel in this realm: its transport, its messages, its settings

The effective transport (capture, smtp, ses, acs, gmail or off) and the setting it came from, whether mail is available, the relay (host, port, TLS, AUTH method, DKIM) for SMTP, the last buildProblem in the answering process, the from address, linkBase (where a mailed link points) and whether it is pinned, the outbox counts, the categories, and templates — every message with its placeholders and the languages this realm has its own wording in — and the Mail settings. No secret is ever in it. With template (and lang), that message’s wording as template.

Mirrors GET /admin/mail on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
template query one of password-reset, account-activation, address-verification, pseudonym-verification, password-changed, account-disabled, sessions-ended, credential-compromised, recovery-started, address-changed, account-connected, access-request, uma-approval, authzen-access-request, authzen-emergency-access, pki-pin-status, administrator-alert, sign-in-code, sign-in-link, report-ready, post-login-reminder, reset-refused-attempt, layout, test-message   A message id, to answer its wording.
lang query string   The language of template; en by default.
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 mail channel’s state in this realm.

Member Type Required What it is
available boolean    
buildProblem object    
buildProblem.at string    
buildProblem.why string    
categories list    
categories[].id string    
categories[].label string    
categories[].optional boolean    
categories[].reason string    
categories[].what string    
counts object    
counts.captured integer    
counts.dead integer    
counts.pending integer    
counts.sent integer    
from string, or null    
linkBase string, or null    
linkBasePinned boolean    
mode string    
realm string    
relay object    
relay.auth string, or number, or boolean, or null    
relay.dkim string    
relay.host string, or null    
relay.port string, or number, or boolean, or null    
relay.tls string, or number, or boolean, or null    
securityNotices boolean    
selfServiceReset boolean    
setting string, or null    
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
template object    
template.category string    
template.html string    
template.id string    
template.lang string    
template.links list    
template.links[] string    
template.own boolean    
template.subject string    
template.text string    
template.title string    
template.values list    
template.values[] string    
templates list    
templates[].builtInLanguages list    
templates[].builtInLanguages[] string    
templates[].category string    
templates[].id string    
templates[].languages list    
templates[].languages[] string    
templates[].links list    
templates[].links[] string    
templates[].title string    
templates[].values list    
templates[].values[] string    
transport string, or null    

400: The answer.

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

GET /admin-api/mail/outbox

getMailOutbox

Every message this realm queued, and what became of it

The outbox, newest first: counts (pending, sent, captured, dead) and rows, each id, username, to, category, template, lang, subject, state, transport, attempts, generation, errorCode, why, providerId, messageId and the times — never a body, in rowsPaging. With message, that one message as message, which carries text and html only when it was CAPTURED (development).

Mirrors GET /admin/mail/outbox on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
state query one of pending, sent, captured, dead   Only messages in this state (dead: the dead letters).
q query string   A person, an address, a message or a code.
message query string   One message’s id.
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 outbox.

Member Type Required What it is
counts object    
counts.captured integer    
counts.dead integer    
counts.pending integer    
counts.sent integer    
message object    
message.actor string, or null    
message.attempts number    
message.bodyKept boolean    
message.category string, or null    
message.errorCode string, or null    
message.finishedAt string    
message.from string, or null    
message.generation number    
message.holder string    
message.html string, or null    
message.id string    
message.inFlight boolean    
message.lang string, or null    
message.lastAttemptAt string    
message.messageId string, or null    
message.nextAttemptAt string    
message.providerId string    
message.queuedAt string    
message.realm string, or null    
message.state string    
message.subject string, or null    
message.template string, or null    
message.text string, or null    
message.to string, or null    
message.transport string, or null    
message.username string, or null    
message.via string, or null    
message.why string, or null    
q string    
realm string    
rows list    
rows[].actor string, or null    
rows[].attempts number    
rows[].bodyKept boolean    
rows[].category string, or null    
rows[].errorCode string, or null    
rows[].finishedAt string    
rows[].from string, or null    
rows[].generation number    
rows[].holder string    
rows[].html string, or null    
rows[].id string    
rows[].inFlight boolean    
rows[].lang string, or null    
rows[].lastAttemptAt string    
rows[].messageId string, or null    
rows[].nextAttemptAt string    
rows[].providerId string    
rows[].queuedAt string    
rows[].realm string, or null    
rows[].state string    
rows[].subject string, or null    
rows[].template string, or null    
rows[].text string, or null    
rows[].to string, or null    
rows[].transport string, or null    
rows[].username string, or null    
rows[].via string, or null    
rows[].why string, or null    
rowsPaging object   Which page of how many, and the query parameter that moves it.
rowsPaging.firstRow integer    
rowsPaging.lastRow integer    
rowsPaging.noun string    
rowsPaging.page integer    
rowsPaging.pages integer    
rowsPaging.param string    
rowsPaging.perPage integer    
rowsPaging.total integer    
state string    
transport string, or null    

400: The answer.

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

POST /admin-api/mail/outbox/retry

retryMailDeadLetter

Send a dead letter again

A new generation of message — a fresh attempt budget, the same body and Message-ID — to the address the person’s entry holds NOW, through the realm’s transport as it is now. Refused (STS-MAIL-0018) for an unknown message, one that is not a dead letter, one that kept no body, or a person with no usable address.

Mirrors POST /admin/mail/outbox 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
message string yes The message id, as the outbox lists it.

200: The message, queued again.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

POST /admin-api/mail/reset-template

resetMailTemplate

Put a message back to the built-in wording

Removes this realm’s wording of template in lang; the built-in English is used again. Refused (STS-MAIL-0017) when there is none.

Mirrors POST /admin/mail 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
lang string yes A BCP 47 tag.
template one of password-reset, account-activation, address-verification, pseudonym-verification, password-changed, account-disabled, sessions-ended, credential-compromised, recovery-started, address-changed, account-connected, access-request, uma-approval, authzen-access-request, authzen-emergency-access, pki-pin-status, administrator-alert, sign-in-code, sign-in-link, report-ready, post-login-reminder, reset-refused-attempt, layout, test-message yes The message id.

200: Whether it was reset.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

POST /admin-api/mail/save-template

saveMailTemplate

Save this realm’s wording of a message in a language

The subject, the text part and the HTML part of template in lang (a BCP 47 tag). Refused (STS-MAIL-0016) when it writes an address of its own (a link is a placeholder), loads or runs anything, uses a placeholder the message does not offer, or leaves a link out of the text part.

Mirrors POST /admin/mail 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
html string yes The HTML part.
lang string yes A BCP 47 tag.
subject string yes One line.
template one of password-reset, account-activation, address-verification, pseudonym-verification, password-changed, account-disabled, sessions-ended, credential-compromised, recovery-started, address-changed, account-connected, access-request, uma-approval, authzen-access-request, authzen-emergency-access, pki-pin-status, administrator-alert, sign-in-code, sign-in-link, report-ready, post-login-reminder, reset-refused-attempt, layout, test-message yes The message id.
text string yes The text part.

200: Whether it was saved.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

POST /admin-api/mail/test

sendMailTestMessage

Send a test message to a person in this realm

Queues the test-message message for user — a person in this realm’s directory — at the address on their entry, through the realm’s transport. Never to an address: there is no parameter for one. Refused (STS-MAIL-0027) when the person has no address, and with the channel’s own code when it refuses to queue (no transport, a ceiling). The outbox shows where it got to.

Mirrors POST /admin/mail 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
user string yes The person, by username.

200: The message queued, and its id.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

POST /admin-api/mail/verify

sendMailVerificationLink

Mail a person a link that verifies their address

A single-use link to /portal/verify-email, mailed to the address on user’s entry and never returned: the person follows it, and the address becomes stsMailVerified. The same link the person’s own button on /portal/email sends. Refused for nobody (STS-MAIL-0012), no address (STS-MAIL-0011) or no transport (STS-MAIL-0032); answers that it is already verified when it is.

Mirrors POST /admin/mail 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
user string yes The person, by username.

200: Whether a link was sent.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
message_id string    
ok boolean yes  
row object    
row.actor string, or null    
row.attempts number    
row.bodyKept boolean    
row.category string, or null    
row.finishedAt string    
row.from string, or null    
row.generation number    
row.holder string    
row.html string, or null    
row.id string    
row.inFlight boolean    
row.lang string, or null    
row.lastAttemptAt string    
row.messageId string, or null    
row.nextAttemptAt string    
row.providerId string    
row.queuedAt string    
row.realm string, or null    
row.state string    
row.subject string, or null    
row.template string, or null    
row.text string, or null    
row.to string, or null    
row.transport string, or null    
row.username string, or null    
row.via string, or null    
row.why string, or null    
verified boolean    

GET /admin-api/malware-scanning

getMalwareScanning

Whether uploaded files are scanned, and by which ICAP service

enabled and url as set; scanning, whether files are being scanned now, which needs both; and the settings the page draws.

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 malware scanning view.

Member Type Required What it is
enabled boolean yes  
scanning boolean yes  
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
url string yes  

POST /admin-api/malware-scanning/test

testMalwareScanning

Check that the configured ICAP service really scans

Sends an ICAP OPTIONS request, then the EICAR test file, which is harmless. It succeeds only if the service flags that file, because a service whose engine failed to load can answer as if every file were clean. A failure is a 400 whose errors says what went wrong.

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.

200: How the service answered.

Member Type Required What it is
message string yes  
ok boolean yes  

400: The test failed or no ICAP service is set; errors says why.

Member Type Required What it is
accepted boolean    
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  
run string   The address to follow the run at.
runId string    

GET /admin-api/me

getMe

Who the caller is here, and what they may do

What this API’s gate decided for the access token on this request: the token’s subject (caller: a person, or a client on client_credentials), the realm that issued it and whether that makes the caller a service or a realm authority, the scopes it carries that its client still declares, the roles its subject holds NOW that those scopes carry, and so whether it may read and write. console reports the roster the answer was read from: whether it is still open to anybody, and the bootstrap administrator’s state. pages is every console page this caller may reach; a realm authority is not given the service pages.

A role granted or revoked since the token was minted shows here at once, because the roles are read on every call. Where no token is required (development mode with adminApi.authRequired off) there is no caller, and both read and write are true.

Mirrors no console page — what the gate decided for the caller; the console draws its banner and its navigation from it 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 caller, the authority, the roles and the pages.

Member Type Required What it is
authority string, or null    
caller object    
caller.clientId string, or null    
caller.kind string    
caller.name string    
console object    
console.available boolean    
console.bootstrap object    
console.bootstrap.claimedAt string    
console.bootstrap.dn string    
console.bootstrap.seeded boolean    
console.bootstrap.username string    
console.bootstrapPasswordRequired boolean    
console.empty boolean    
console.open boolean    
console.windowOpens boolean    
expiresAt number, or null    
mode string    
pages list    
pages[] string    
photo string   This person’s photo on this realm, empty where they have none.
read boolean    
readGroup string, or null    
readingRealm string   The realm this request was read in.
realm string   The realm the caller belongs to: the one that issued the token.
roles list    
roles[] string    
scopes list    
scopes[] string    
security boolean    
tokenRequired boolean   Whether this API requires an access token, in force.
write boolean    
writeGroup string, or null    

GET /admin-api/mode

getMode

What global.mode changes, and what is in force in this realm

The mode of the realm the call is in (mode, isProduct) and everything it decides: requirements — each with id, what, the development and product answers, inForce (the one this realm gives) and where it is implemented (and, on oauth-security-bcp, waived — each RFC 9700 requirement an administrator waived in this realm, with its requirement, section, level and the setting that waives it, #1295; and, since #1296, perApplication, the attribute that enables a waived type on one application and dynamicRegistration — the setting naming which a self-registering client may enable, and its value); developmentOnlySettings — every setting whose row is marked development-only, with key, group, the predicate in common/mode.js that must answer yes, developmentOnlyValues (null when every value but the default is), default, the value stored, the value inForce, ignored (true exactly where a product realm holds a development-only value, which is read as the default) and why; and notYet — what product mode still does not check, each with id and what. The mode is per trust realm, so call it under /realm/{id}/admin-api/mode for a realm.

Mirrors GET /admin/mode 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 mode report.

Member Type Required What it is
developmentOnlySettings list    
developmentOnlySettings[].default list, or string, or number, or boolean, or null    
developmentOnlySettings[].default[] string, or number, or boolean    
developmentOnlySettings[].developmentOnlyValues list    
developmentOnlySettings[].developmentOnlyValues[] string    
developmentOnlySettings[].group string    
developmentOnlySettings[].ignored boolean    
developmentOnlySettings[].inForce list, or string, or number, or boolean, or null    
developmentOnlySettings[].inForce[] string, or number, or boolean    
developmentOnlySettings[].key string    
developmentOnlySettings[].predicate string    
developmentOnlySettings[].value list, or string, or number, or boolean, or null    
developmentOnlySettings[].value[] string, or number, or boolean    
developmentOnlySettings[].why string    
isProduct boolean    
mode string    
notYet list    
notYet[].id string    
notYet[].what string    
requirements list    
requirements[].development string    
requirements[].id string    
requirements[].inForce string    
requirements[].product string    
requirements[].waived list    
requirements[].waived[].attribute string    
requirements[].waived[].dynamicRegistration object    
requirements[].waived[].dynamicRegistration.setting string    
requirements[].waived[].dynamicRegistration.value list, or string, or number, or boolean, or null    
requirements[].waived[].dynamicRegistration.value[] string, or number, or boolean    
requirements[].waived[].level string    
requirements[].waived[].perApplication boolean    
requirements[].waived[].requirement string    
requirements[].waived[].section string    
requirements[].waived[].setting string    
requirements[].what string    
requirements[].where string    

GET /admin-api/node-health

getNodeHealth

The CPU and memory of this node’s container, and the Node.js memory of each of its processes and worker threads

Always generatedAt, node, pid (the front process that answered), scope (node), scopeText and cgroup (the cgroup v2 directory read, or null). cpu: available, and either unavailableText or utilisationPercent — CPU time from cpu.stat over windowSeconds (sampled since-previous-sample or fresh-sample), as a share of percentOfVcpus — coresUsed, limitVcpus (from cpu.max; null for no quota, when the share is of os.availableParallelism(), which limitText says), usageSeconds, userSeconds, systemSeconds and throttling. Both say which cgroup they came from (cgroupVersion, 2 or 1); a limit that means none is the ECS task’s where the agent answers (limitSource ecs-task), and with no cgroup at all the figures are the agent’s (fromEcs). memory: available, and either unavailableText or currentBytes (memory.current), limitBytes (memory.max; null for none), utilisationPercent, peakBytes, anonBytes, fileBytes, kernelBytes and oomKills. processes: rows, each with kind (process or thread), pid and threadId — the front process (process.memoryUsage(): rssBytes, heapUsedBytes, heapTotalBytes, externalBytes, arrayBuffersBytes, and CPU time; its resident size and CPU time are the whole process’s, every thread’s included, processWide says so); each request and hosted-surface worker THREAD of it (#364) that answered within a second, with its own heap figures and rssBytes and CPU time null, because in a thread those are the process’s; and the debugger’s api child, the five figures when it answered within half a second, and otherwise rssBytes and peakRssBytes from /proc/<pid>/status, the heap figures null and notReported saying why — unanswered (worker threads that did not answer, by threadId; a thread has no /proc entry to fall back on), and totals (rows, processes, workerThreads, rssBytes over processes only, processesWithRss, the heap sums over every isolate and isolatesWithHeap). ecs: the ECS task metadata endpoint’s taskLimits and stats where ECS_CONTAINER_METADATA_URI_V4 is set, and available: false with a sentence where it is not. machine: os.loadavg(), os.totalmem(), os.freemem() and the CPU count, which describe the machine (on Fargate the micro-VM) and NOT the container. THE TOP-LEVEL FIGURES ARE THIS NODE’S (node names it; never a host or an address). In a cluster, nodes has a section per node — this one live, every other from the snapshot it writes every 15 s, each with name, self, state (live, stale past 45 s, gone from cluster membership, no-snapshot), stateText, ageSeconds and view — and totals sums container memory and its limit, CPU, the processes and the worker threads over the nodes not gone; cluster says whether there is one. answeredBy names the node that answered (#332). A service operation: a realm’s own administrator is refused it.

Mirrors GET /admin/node-health on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
node query string   A cluster node’s NAME (cluster.nodeName, node-a, node-b, …), to answer about that node alone: its view at the top, nodes holding its one section. An unknown name is 404 with the names there are (#332).
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 container and its processes.

Member Type Required What it is
answeredBy object    
answeredBy.node string, or null    
answeredBy.pid integer    
cgroup string, or null    
cgroupVersion integer, or null    
cluster object    
cluster.clustered boolean    
cluster.goneRemovedAfterHours number    
cluster.intervalSeconds number    
cluster.readError string, or null    
cluster.staleAfterSeconds number    
cluster.text string    
cpu object    
cpu.available boolean    
cpu.cgroupUnavailableText string, or null    
cpu.cgroupVersion integer, or null    
cpu.coresUsed number, or null    
cpu.fromEcs boolean    
cpu.limitSource string, or null    
cpu.limitText string, or null    
cpu.limitVcpus number, or null    
cpu.percentOfVcpus number, or null    
cpu.sampled string, or null    
cpu.source string, or null    
cpu.systemSeconds number, or null    
cpu.throttling object    
cpu.throttling.periods number, or null    
cpu.throttling.throttledPercentOfPeriods number, or null    
cpu.throttling.throttledPeriods number, or null    
cpu.throttling.throttledSeconds number, or null    
cpu.throttlingText string, or null    
cpu.unavailableText string, or null    
cpu.usageSeconds number, or null    
cpu.userSeconds number, or null    
cpu.utilisationPercent number, or null    
cpu.windowSeconds number, or null    
ecs object    
ecs.available boolean    
ecs.containerLimits map   ECS’s Limits, as it said them.
ecs.containerLimits.{key} string, or number, or boolean, or null    
ecs.dockerId string, or null    
ecs.endpoint string    
ecs.stats object    
ecs.stats.cpuCoresUsed number, or null    
ecs.stats.cpuPercentOfTaskLimit number, or null    
ecs.stats.memoryLimitBytes number, or null    
ecs.stats.memoryLimitUnlimited boolean    
ecs.stats.memoryUsageBytes number, or null    
ecs.stats.read string, or null    
ecs.taskLimits object    
ecs.taskLimits.cpuVcpus string, or number, or boolean, or null    
ecs.taskLimits.memoryMiB string, or number, or boolean, or null    
ecs.text string    
ecs.unavailableText string, or null    
generatedAt string    
machine object    
machine.cpus integer    
machine.freememBytes number    
machine.loadavg list    
machine.loadavg[] number    
machine.text string    
machine.totalmemBytes number    
memory object    
memory.anonBytes number, or null    
memory.available boolean    
memory.cgroupUnavailableText string, or null    
memory.cgroupVersion integer, or null    
memory.currentBytes number, or null    
memory.fileBytes number, or null    
memory.fromEcs boolean    
memory.kernelBytes number, or null    
memory.limitBytes number, or null    
memory.limitSource string, or null    
memory.limitText string, or null    
memory.oomKills number, or null    
memory.peakBytes number, or null    
memory.source string, or null    
memory.statText string, or null    
memory.unavailableText string, or null    
memory.utilisationPercent number, or null    
node string, or null    
nodes list    
nodes[].ageSeconds number, or null    
nodes[].name string    
nodes[].self boolean    
nodes[].state string    
nodes[].stateText string    
nodes[].takenAt string, or null    
nodes[].view object    
nodes[].view.cgroup string, or null    
nodes[].view.cgroupVersion integer, or null    
nodes[].view.cpu object    
nodes[].view.cpu.available boolean    
nodes[].view.cpu.cgroupUnavailableText string, or null    
nodes[].view.cpu.cgroupVersion integer, or null    
nodes[].view.cpu.coresUsed number, or null    
nodes[].view.cpu.fromEcs boolean    
nodes[].view.cpu.limitSource string, or null    
nodes[].view.cpu.limitText string, or null    
nodes[].view.cpu.limitVcpus number, or null    
nodes[].view.cpu.percentOfVcpus number, or null    
nodes[].view.cpu.sampled string, or null    
nodes[].view.cpu.source string, or null    
nodes[].view.cpu.systemSeconds number, or null    
nodes[].view.cpu.throttling object    
nodes[].view.cpu.throttling.periods number, or null    
nodes[].view.cpu.throttling.throttledPercentOfPeriods number, or null    
nodes[].view.cpu.throttling.throttledPeriods number, or null    
nodes[].view.cpu.throttling.throttledSeconds number, or null    
nodes[].view.cpu.throttlingText string, or null    
nodes[].view.cpu.unavailableText string, or null    
nodes[].view.cpu.usageSeconds number, or null    
nodes[].view.cpu.userSeconds number, or null    
nodes[].view.cpu.utilisationPercent number, or null    
nodes[].view.cpu.windowSeconds number, or null    
nodes[].view.ecs object    
nodes[].view.ecs.available boolean    
nodes[].view.ecs.containerLimits map   ECS’s Limits, as it said them.
nodes[].view.ecs.containerLimits.{key} string, or number, or boolean, or null    
nodes[].view.ecs.dockerId string, or null    
nodes[].view.ecs.endpoint string    
nodes[].view.ecs.stats object    
nodes[].view.ecs.stats.cpuCoresUsed number, or null    
nodes[].view.ecs.stats.cpuPercentOfTaskLimit number, or null    
nodes[].view.ecs.stats.memoryLimitBytes number, or null    
nodes[].view.ecs.stats.memoryLimitUnlimited boolean    
nodes[].view.ecs.stats.memoryUsageBytes number, or null    
nodes[].view.ecs.stats.read string, or null    
nodes[].view.ecs.taskLimits object    
nodes[].view.ecs.taskLimits.cpuVcpus string, or number, or boolean, or null    
nodes[].view.ecs.taskLimits.memoryMiB string, or number, or boolean, or null    
nodes[].view.ecs.text string    
nodes[].view.ecs.unavailableText string, or null    
nodes[].view.generatedAt string    
nodes[].view.machine object    
nodes[].view.machine.cpus integer    
nodes[].view.machine.freememBytes number    
nodes[].view.machine.loadavg list    
nodes[].view.machine.loadavg[] number    
nodes[].view.machine.text string    
nodes[].view.machine.totalmemBytes number    
nodes[].view.memory object    
nodes[].view.memory.anonBytes number, or null    
nodes[].view.memory.available boolean    
nodes[].view.memory.cgroupUnavailableText string, or null    
nodes[].view.memory.cgroupVersion integer, or null    
nodes[].view.memory.currentBytes number, or null    
nodes[].view.memory.fileBytes number, or null    
nodes[].view.memory.fromEcs boolean    
nodes[].view.memory.kernelBytes number, or null    
nodes[].view.memory.limitBytes number, or null    
nodes[].view.memory.limitSource string, or null    
nodes[].view.memory.limitText string, or null    
nodes[].view.memory.oomKills number, or null    
nodes[].view.memory.peakBytes number, or null    
nodes[].view.memory.source string, or null    
nodes[].view.memory.statText string, or null    
nodes[].view.memory.unavailableText string, or null    
nodes[].view.memory.utilisationPercent number, or null    
nodes[].view.node string, or null    
nodes[].view.pid integer, or null    
nodes[].view.processes object    
nodes[].view.processes.debuggerNote string, or null    
nodes[].view.processes.rows list    
nodes[].view.processes.rows[].arrayBuffersBytes number, or null    
nodes[].view.processes.rows[].cpuSystemSeconds number, or null    
nodes[].view.processes.rows[].cpuUserSeconds number, or null    
nodes[].view.processes.rows[].externalBytes number, or null    
nodes[].view.processes.rows[].heapTotalBytes number, or null    
nodes[].view.processes.rows[].heapUsedBytes number, or null    
nodes[].view.processes.rows[].kind string    
nodes[].view.processes.rows[].notReported string    
nodes[].view.processes.rows[].peakRssBytes number, or null    
nodes[].view.processes.rows[].pid integer, or string, or null    
nodes[].view.processes.rows[].processWide string    
nodes[].view.processes.rows[].role string    
nodes[].view.processes.rows[].rssBytes number, or null    
nodes[].view.processes.rows[].source string    
nodes[].view.processes.rows[].threadId integer, or string, or null    
nodes[].view.processes.rows[].unreadable string, or null    
nodes[].view.processes.rows[].uptimeSeconds number, or null    
nodes[].view.processes.totals object    
nodes[].view.processes.totals.externalBytes number    
nodes[].view.processes.totals.heapTotalBytes number    
nodes[].view.processes.totals.heapUsedBytes number    
nodes[].view.processes.totals.isolatesWithHeap integer    
nodes[].view.processes.totals.processes integer    
nodes[].view.processes.totals.processesWithRss integer    
nodes[].view.processes.totals.rows integer    
nodes[].view.processes.totals.rssBytes number    
nodes[].view.processes.totals.workerThreads integer    
nodes[].view.processes.totalsText string    
nodes[].view.processes.unanswered list    
nodes[].view.processes.unanswered[].pid integer, or string, or null    
nodes[].view.processes.unanswered[].role string    
nodes[].view.processes.unanswered[].threadId integer, or string, or null    
nodes[].view.processes.unanswered[].why string    
nodes[].view.scope string    
nodes[].view.scopeText string    
pid integer, or null    
processes object    
processes.debuggerNote string, or null    
processes.rows list    
processes.rows[].arrayBuffersBytes number, or null    
processes.rows[].cpuSystemSeconds number, or null    
processes.rows[].cpuUserSeconds number, or null    
processes.rows[].externalBytes number, or null    
processes.rows[].heapTotalBytes number, or null    
processes.rows[].heapUsedBytes number, or null    
processes.rows[].kind string    
processes.rows[].notReported string    
processes.rows[].peakRssBytes number, or null    
processes.rows[].pid integer, or string, or null    
processes.rows[].processWide string    
processes.rows[].role string    
processes.rows[].rssBytes number, or null    
processes.rows[].source string    
processes.rows[].threadId integer, or string, or null    
processes.rows[].unreadable string, or null    
processes.rows[].uptimeSeconds number, or null    
processes.totals object    
processes.totals.externalBytes number    
processes.totals.heapTotalBytes number    
processes.totals.heapUsedBytes number    
processes.totals.isolatesWithHeap integer    
processes.totals.processes integer    
processes.totals.processesWithRss integer    
processes.totals.rows integer    
processes.totals.rssBytes number    
processes.totals.workerThreads integer    
processes.totalsText string    
processes.unanswered list    
processes.unanswered[].pid integer, or string, or null    
processes.unanswered[].role string    
processes.unanswered[].threadId integer, or string, or null    
processes.unanswered[].why string    
scope string    
scopeText string    
state string    
totals object    
totals.cpuCoresUsed number, or null    
totals.cpuNodes integer    
totals.cpuOf number, or null    
totals.cpuPercent number, or null    
totals.heapUsedBytes number    
totals.memoryLimitBytes number, or null    
totals.memoryNodes integer    
totals.memoryPercent number, or null    
totals.memoryUsedBytes number, or null    
totals.nodes integer    
totals.nodesCounted integer    
totals.processes integer    
totals.rssBytes number    
totals.text string    
totals.workerThreads integer    

404: The answer.

Member Type Required What it is
errors list    
errors[] string    
nodes list   The nodes there are.
nodes[] string    
ok boolean    

POST /admin-api/node-health/collect-garbage

collectGarbage

Run a full V8 garbage collection in this node’s front process, one of its worker threads, or all

THIS NODE only — the front process that answers and its own request and hosted-surface worker THREADS, never another node of a cluster. target is all (the default: the front process’s main thread and every ready worker thread), front, or a worker thread’s threadId as GET /admin-api/node-health lists it. Each worker thread is a V8 isolate of its own and collects itself, asked over the pool’s channel and waited for up to ten seconds. A FULL COLLECTION STOPS THE THREAD IT RUNS IN UNTIL IT FINISHES; in the front process that pauses every listener of the node. A diagnostic. Answers 200 with rows, one per isolate collected or asked (kind process or thread, pid, threadId, role, ok, heapUsedBeforeBytes, heapTotalBeforeBytes, heapUsedAfterBytes, heapTotalAfterBytes, freedBytes, durationMs — the pause — and error), unanswered (worker threads that did not answer in time), totals and message; 400 for an unknown action or a malformed target, 404 for a thread this node does not have, 500 when the front process alone was asked and could not collect. Audited. A service operation: a realm’s own administrator is refused it.

Mirrors POST /admin/node-health 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 (optional)

Member Type Required What it is
target string, or integer   all, front, or a worker thread’s threadId; all when absent.

200: Each isolate’s heap before and after its collection, and the pause.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
generatedAt string    
message string    
node string, or null    
ok boolean yes  
pid integer    
rows list    
rows[].durationMs number, or null    
rows[].error string, or null    
rows[].freedBytes number, or null    
rows[].heapTotalAfterBytes number, or null    
rows[].heapTotalBeforeBytes number, or null    
rows[].heapUsedAfterBytes number, or null    
rows[].heapUsedBeforeBytes number, or null    
rows[].kind string    
rows[].ok boolean    
rows[].pid integer    
rows[].role string    
rows[].threadId integer, or null    
target string    
threadIds list    
threadIds[] string    
totals object    
totals.collected integer    
totals.failed integer    
totals.freedBytes number    
totals.isolates integer    
totals.longestPauseMs number    
totals.unanswered integer    
unanswered list    
unanswered[].pid integer    
unanswered[].role string    
unanswered[].threadId integer, or null    
unanswered[].why string    

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

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
generatedAt string    
message string    
node string, or null    
ok boolean yes  
pid integer    
rows list    
rows[].durationMs number, or null    
rows[].error string, or null    
rows[].freedBytes number, or null    
rows[].heapTotalAfterBytes number, or null    
rows[].heapTotalBeforeBytes number, or null    
rows[].heapUsedAfterBytes number, or null    
rows[].heapUsedBeforeBytes number, or null    
rows[].kind string    
rows[].ok boolean    
rows[].pid integer    
rows[].role string    
rows[].threadId integer, or null    
target string    
threadIds list    
threadIds[] string    
totals object    
totals.collected integer    
totals.failed integer    
totals.freedBytes number    
totals.isolates integer    
totals.longestPauseMs number    
totals.unanswered integer    
unanswered list    
unanswered[].pid integer    
unanswered[].role string    
unanswered[].threadId integer, or null    
unanswered[].why string    

404: The answer.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
generatedAt string    
message string    
node string, or null    
ok boolean yes  
pid integer    
rows list    
rows[].durationMs number, or null    
rows[].error string, or null    
rows[].freedBytes number, or null    
rows[].heapTotalAfterBytes number, or null    
rows[].heapTotalBeforeBytes number, or null    
rows[].heapUsedAfterBytes number, or null    
rows[].heapUsedBeforeBytes number, or null    
rows[].kind string    
rows[].ok boolean    
rows[].pid integer    
rows[].role string    
rows[].threadId integer, or null    
target string    
threadIds list    
threadIds[] string    
totals object    
totals.collected integer    
totals.failed integer    
totals.freedBytes number    
totals.isolates integer    
totals.longestPauseMs number    
totals.unanswered integer    
unanswered list    
unanswered[].pid integer    
unanswered[].role string    
unanswered[].threadId integer, or null    
unanswered[].why string    

500: The answer.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
generatedAt string    
message string    
node string, or null    
ok boolean yes  
pid integer    
rows list    
rows[].durationMs number, or null    
rows[].error string, or null    
rows[].freedBytes number, or null    
rows[].heapTotalAfterBytes number, or null    
rows[].heapTotalBeforeBytes number, or null    
rows[].heapUsedAfterBytes number, or null    
rows[].heapUsedBeforeBytes number, or null    
rows[].kind string    
rows[].ok boolean    
rows[].pid integer    
rows[].role string    
rows[].threadId integer, or null    
target string    
threadIds list    
threadIds[] string    
totals object    
totals.collected integer    
totals.failed integer    
totals.freedBytes number    
totals.isolates integer    
totals.longestPauseMs number    
totals.unanswered integer    
unanswered list    
unanswered[].pid integer    
unanswered[].role string    
unanswered[].threadId integer, or null    
unanswered[].why string    

GET /admin-api/openapi.json

getOpenApi

The OpenAPI 3.1 document for this API

Built from the same table that registers the routes, so it describes what is actually there. servers[0].url is this service as the request reached it, so a document fetched through a proxy or a published port names the address the caller can use.

Mirrors GET /admin/sts-metadata 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 document.

Member Type Required What it is
components any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
info any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
openapi string    
paths any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
security any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
servers any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.
tags any JSON   An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table. An OpenAPI 3.1 document’s own contents: their shape is OpenAPI’s, not this service’s, and they are generated from the route table.

GET /admin-api/scheduler

getScheduler

Every scheduled job, its last run and its next, or one run

Without run: the scheduler’s leader (node, nodeName, host, pid, since, token, lastTickAt, live, clustered, thisProcess), and one row in jobs for EVERY registered job, including one that is off — id, title, describe, owner, kind (cluster or per-process), scope (service or realm) and realm, schedule (text, everyMs, setting, cron, manualOnly), state (enabled or off) and offReason, manual (whether it may be run now), runsOn (worker, front or every-process, #408) with onFront (why a cluster job stays on the front process) and nice (0 to 19), lastRun and running (a run: runId, state, attempt, fenceAt, node, pid, startedAt, endedAt, durationMs, ranIn (worker or front), deferredMs (how long it was held for a busy worker), errorCode, why), queued manual runs, nextRunAt (absolute, UTC), nextRunInMs (by the DATABASE’s clock at the time of the request, so every node answers the same figure) and nextRunState (scheduled, due, overdue, running, queued, manual-only or off), and for a per-process job processes[], one per node and process. Then the recent runs, newest first, filtered by job and outcome and answered in runsPaging, and the queued commands. With run: that run, as detail, or found: false. Everything is read from the store, so any node answers the same. A realm’s own administrator sees the service jobs read-only and their own realm’s rows only.

Mirrors GET /admin/scheduler on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
jobsPage query integer   Which page of the job register to return, answered by jobsPaging.
run query string   A run id, to answer that run.
job query string   Only the runs of this job.
outcome query one of succeeded, failed, abandoned, running, queued   Only the runs in this state.
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 scheduler’s report, or one run.

Member Type Required What it is
answeredBy object    
answeredBy.host string    
answeredBy.node string    
answeredBy.nodeName string    
answeredBy.pid integer    
clock string    
commands list    
commands[].command string    
commands[].endedAt string, or null    
commands[].id string    
commands[].leaderAtRequest object    
commands[].leaderAtRequest.node string, or null    
commands[].leaderAtRequest.pid integer, or null    
commands[].leaderAtRequest.token number, or null    
commands[].obeyedBy object, or string, or null    
commands[].obeyedBy.host string, or null    
commands[].obeyedBy.node string, or null    
commands[].obeyedBy.nodeName string, or null    
commands[].obeyedBy.pid integer, or null    
commands[].queuedAt string, or null    
commands[].requestedBy string    
commands[].state string    
confinedToRealm string, or null    
detail object    
detail.abandonedOf string, or null    
detail.attempt integer    
detail.deferredMs number    
detail.dueAt string, or null    
detail.durationMs number, or null    
detail.endedAt string, or null    
detail.errorCode string    
detail.fenceAt number    
detail.host string    
detail.jobId string, or null    
detail.nextRunAt string, or null    
detail.nextRunInMs number, or null    
detail.node string    
detail.nodeName string    
detail.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
detail.pid integer, or null    
detail.queuedAt string, or null    
detail.queuedAtMs number, or null    
detail.ranIn string, or null    
detail.realm string, or null    
detail.requestedBy string    
detail.requestedVia string    
detail.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
detail.runId string    
detail.stale boolean    
detail.startedAt string, or null    
detail.state string    
detail.takenOver boolean    
detail.trigger string    
detail.why string    
detail.worker boolean    
enabled boolean    
filters object    
filters.job string, or null    
filters.outcome string, or null    
found boolean    
generatedAt string    
jobIds list    
jobIds[] string    
jobs list    
jobs[].describe string    
jobs[].id string    
jobs[].kind string    
jobs[].lastRun object    
jobs[].lastRun.abandonedOf string, or null    
jobs[].lastRun.attempt integer    
jobs[].lastRun.deferredMs number    
jobs[].lastRun.dueAt string, or null    
jobs[].lastRun.durationMs number, or null    
jobs[].lastRun.endedAt string, or null    
jobs[].lastRun.errorCode string    
jobs[].lastRun.fenceAt number    
jobs[].lastRun.host string    
jobs[].lastRun.jobId string, or null    
jobs[].lastRun.nextRunAt string, or null    
jobs[].lastRun.nextRunInMs number, or null    
jobs[].lastRun.node string    
jobs[].lastRun.nodeName string    
jobs[].lastRun.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
jobs[].lastRun.pid integer, or null    
jobs[].lastRun.queuedAt string, or null    
jobs[].lastRun.queuedAtMs number, or null    
jobs[].lastRun.ranIn string, or null    
jobs[].lastRun.realm string, or null    
jobs[].lastRun.requestedBy string    
jobs[].lastRun.requestedVia string    
jobs[].lastRun.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
jobs[].lastRun.runId string    
jobs[].lastRun.stale boolean    
jobs[].lastRun.startedAt string, or null    
jobs[].lastRun.state string    
jobs[].lastRun.takenOver boolean    
jobs[].lastRun.trigger string    
jobs[].lastRun.why string    
jobs[].lastRun.worker boolean    
jobs[].manual boolean    
jobs[].nextRunAt string, or null    
jobs[].nextRunInMs number, or null    
jobs[].nextRunState string    
jobs[].nice number    
jobs[].offReason string, or null    
jobs[].onFront string, or null    
jobs[].overdueSince string, or null    
jobs[].overdueWhy string, or null    
jobs[].owner string    
jobs[].processes list    
jobs[].processes[].abandonedOf string, or null    
jobs[].processes[].attempt integer    
jobs[].processes[].deferredMs number    
jobs[].processes[].dueAt string, or null    
jobs[].processes[].durationMs number, or null    
jobs[].processes[].endedAt string, or null    
jobs[].processes[].errorCode string    
jobs[].processes[].fenceAt number    
jobs[].processes[].host string    
jobs[].processes[].jobId string, or null    
jobs[].processes[].nextRunAt string, or null    
jobs[].processes[].nextRunInMs number, or null    
jobs[].processes[].node string    
jobs[].processes[].nodeName string    
jobs[].processes[].params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
jobs[].processes[].pid integer, or null    
jobs[].processes[].queuedAt string, or null    
jobs[].processes[].queuedAtMs number, or null    
jobs[].processes[].ranIn string, or null    
jobs[].processes[].realm string, or null    
jobs[].processes[].requestedBy string    
jobs[].processes[].requestedVia string    
jobs[].processes[].result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
jobs[].processes[].runId string    
jobs[].processes[].stale boolean    
jobs[].processes[].startedAt string, or null    
jobs[].processes[].state string    
jobs[].processes[].takenOver boolean    
jobs[].processes[].trigger string    
jobs[].processes[].why string    
jobs[].processes[].worker boolean    
jobs[].queued list    
jobs[].queued[].abandonedOf string, or null    
jobs[].queued[].attempt integer    
jobs[].queued[].deferredMs number    
jobs[].queued[].dueAt string, or null    
jobs[].queued[].durationMs number, or null    
jobs[].queued[].endedAt string, or null    
jobs[].queued[].errorCode string    
jobs[].queued[].fenceAt number    
jobs[].queued[].host string    
jobs[].queued[].jobId string, or null    
jobs[].queued[].nextRunAt string, or null    
jobs[].queued[].nextRunInMs number, or null    
jobs[].queued[].node string    
jobs[].queued[].nodeName string    
jobs[].queued[].params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
jobs[].queued[].pid integer, or null    
jobs[].queued[].queuedAt string, or null    
jobs[].queued[].queuedAtMs number, or null    
jobs[].queued[].ranIn string, or null    
jobs[].queued[].realm string, or null    
jobs[].queued[].requestedBy string    
jobs[].queued[].requestedVia string    
jobs[].queued[].result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
jobs[].queued[].runId string    
jobs[].queued[].stale boolean    
jobs[].queued[].startedAt string, or null    
jobs[].queued[].state string    
jobs[].queued[].takenOver boolean    
jobs[].queued[].trigger string    
jobs[].queued[].why string    
jobs[].queued[].worker boolean    
jobs[].readOnly boolean    
jobs[].realm string    
jobs[].running object    
jobs[].running.abandonedOf string, or null    
jobs[].running.attempt integer    
jobs[].running.deferredMs number    
jobs[].running.dueAt string, or null    
jobs[].running.durationMs number, or null    
jobs[].running.endedAt string, or null    
jobs[].running.errorCode string    
jobs[].running.fenceAt number    
jobs[].running.host string    
jobs[].running.jobId string, or null    
jobs[].running.nextRunAt string, or null    
jobs[].running.nextRunInMs number, or null    
jobs[].running.node string    
jobs[].running.nodeName string    
jobs[].running.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
jobs[].running.pid integer, or null    
jobs[].running.queuedAt string, or null    
jobs[].running.queuedAtMs number, or null    
jobs[].running.ranIn string, or null    
jobs[].running.realm string, or null    
jobs[].running.requestedBy string    
jobs[].running.requestedVia string    
jobs[].running.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
jobs[].running.runId string    
jobs[].running.stale boolean    
jobs[].running.startedAt string, or null    
jobs[].running.state string    
jobs[].running.takenOver boolean    
jobs[].running.trigger string    
jobs[].running.why string    
jobs[].running.worker boolean    
jobs[].runsOn string    
jobs[].schedule object    
jobs[].schedule.cron string, or null    
jobs[].schedule.everyMs number, or null    
jobs[].schedule.manualOnly boolean    
jobs[].schedule.setting string, or null    
jobs[].schedule.text string    
jobs[].scope string    
jobs[].state string    
jobs[].timeoutMs number    
jobs[].title string    
jobsPaging object   Which page of how many, and the query parameter that moves it.
jobsPaging.firstRow integer    
jobsPaging.lastRow integer    
jobsPaging.noun string    
jobsPaging.page integer    
jobsPaging.pages integer    
jobsPaging.param string    
jobsPaging.perPage integer    
jobsPaging.total integer    
leader object    
leader.clustered boolean    
leader.host string, or null    
leader.known boolean    
leader.lastTickAgoMs number, or null    
leader.lastTickAt string, or null    
leader.leaseAcquiredAt string, or null    
leader.leaseExpiresAt string, or null    
leader.leaseHolder string, or null    
leader.live boolean, or null    
leader.node string, or null    
leader.nodeName string, or null    
leader.pid integer, or null    
leader.since string, or null    
leader.thisProcess boolean, or null    
leader.token number, or null    
nowMs number    
run string   The run asked for by ?run=.
runs list    
runs[].abandonedOf string, or null    
runs[].attempt integer    
runs[].deferredMs number    
runs[].dueAt string, or null    
runs[].durationMs number, or null    
runs[].endedAt string, or null    
runs[].errorCode string    
runs[].fenceAt number    
runs[].host string    
runs[].jobId string, or null    
runs[].nextRunAt string, or null    
runs[].nextRunInMs number, or null    
runs[].node string    
runs[].nodeName string    
runs[].params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
runs[].pid integer, or null    
runs[].queuedAt string, or null    
runs[].queuedAtMs number, or null    
runs[].ranIn string, or null    
runs[].realm string, or null    
runs[].requestedBy string    
runs[].requestedVia string    
runs[].result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
runs[].runId string    
runs[].stale boolean    
runs[].startedAt string, or null    
runs[].state string    
runs[].takenOver boolean    
runs[].trigger string    
runs[].why string    
runs[].worker boolean    
runsPaging object   Which page of how many, and the query parameter that moves it.
runsPaging.firstRow integer    
runsPaging.lastRow integer    
runsPaging.noun string    
runsPaging.page integer    
runsPaging.pages integer    
runsPaging.param string    
runsPaging.perPage integer    
runsPaging.total integer    
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
tickS number    
unknownDisabledIds list    
unknownDisabledIds[] string    

400: The answer.

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

POST /admin-api/scheduler/run

runSchedulerJob

Queue a run of one job now

Writes a queued run of job (in realm, for a realm-scoped job) that the scheduler’s leader starts at its next tick, wherever this request was answered — 202 with its runId and href. A second request while one is queued answers the same run (alreadyQueued). Refused 404 for an unknown job, 400 for a job that runs on its schedule only, is off (with the reason: its setting, scheduler.enabled, or development mode), or names a realm that does not exist; 403 to a realm administrator for a service job or another realm.

Mirrors POST /admin/scheduler 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
job string yes The job id, as GET /admin-api/scheduler lists it.
params object   Parameters the job reads, where it reads any.
realm string   The realm, for a realm-scoped job; the one the request is in otherwise.

200: The queued run.

Member Type Required What it is
accepted boolean    
alreadyQueued boolean    
command string    
error string    
error_description string    
errors list    
errors[] string    
href string    
leaderAtRequest object    
leaderAtRequest.node string, or null    
leaderAtRequest.pid integer, or null    
leaderAtRequest.token number, or null    
message string    
ok boolean yes  
run object    
run.abandonedOf string, or null    
run.attempt integer    
run.deferredMs number    
run.dueAt string, or null    
run.durationMs number, or null    
run.endedAt string, or null    
run.fenceAt number    
run.host string    
run.jobId string, or null    
run.nextRunAt string, or null    
run.nextRunInMs number, or null    
run.node string    
run.nodeName string    
run.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
run.pid integer, or null    
run.queuedAt string, or null    
run.queuedAtMs number, or null    
run.ranIn string, or null    
run.realm string, or null    
run.requestedBy string    
run.requestedVia string    
run.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
run.runId string    
run.stale boolean    
run.startedAt string, or null    
run.state string    
run.takenOver boolean    
run.trigger string    
run.why string    
run.worker boolean    
runId string    

202: The answer.

Member Type Required What it is
accepted boolean    
alreadyQueued boolean    
command string    
error string    
error_description string    
errors list    
errors[] string    
href string    
leaderAtRequest object    
leaderAtRequest.node string, or null    
leaderAtRequest.pid integer, or null    
leaderAtRequest.token number, or null    
message string    
ok boolean yes  
run object    
run.abandonedOf string, or null    
run.attempt integer    
run.deferredMs number    
run.dueAt string, or null    
run.durationMs number, or null    
run.endedAt string, or null    
run.fenceAt number    
run.host string    
run.jobId string, or null    
run.nextRunAt string, or null    
run.nextRunInMs number, or null    
run.node string    
run.nodeName string    
run.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
run.pid integer, or null    
run.queuedAt string, or null    
run.queuedAtMs number, or null    
run.ranIn string, or null    
run.realm string, or null    
run.requestedBy string    
run.requestedVia string    
run.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
run.runId string    
run.stale boolean    
run.startedAt string, or null    
run.state string    
run.takenOver boolean    
run.trigger string    
run.why string    
run.worker boolean    
runId string    

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

Member Type Required What it is
accepted boolean    
alreadyQueued boolean    
command string    
error string    
error_description string    
errors list    
errors[] string    
href string    
leaderAtRequest object    
leaderAtRequest.node string, or null    
leaderAtRequest.pid integer, or null    
leaderAtRequest.token number, or null    
message string    
ok boolean yes  
run object    
run.abandonedOf string, or null    
run.attempt integer    
run.deferredMs number    
run.dueAt string, or null    
run.durationMs number, or null    
run.endedAt string, or null    
run.fenceAt number    
run.host string    
run.jobId string, or null    
run.nextRunAt string, or null    
run.nextRunInMs number, or null    
run.node string    
run.nodeName string    
run.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
run.pid integer, or null    
run.queuedAt string, or null    
run.queuedAtMs number, or null    
run.ranIn string, or null    
run.realm string, or null    
run.requestedBy string    
run.requestedVia string    
run.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
run.runId string    
run.stale boolean    
run.startedAt string, or null    
run.state string    
run.takenOver boolean    
run.trigger string    
run.why string    
run.worker boolean    
runId string    

POST /admin-api/scheduler/step-down

stepDownScheduler

Ask the scheduler’s leader to hand over

Writes a command the leader obeys at its next tick: it gives up the ops.scheduler lease and does not ask for it again for three heartbeats, so another node takes the lead. A planned handover, and a way to drain a node. 202; 400 when the service is not clustered (STS-SCHED-0010). A service operation.

Mirrors POST /admin/scheduler 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 (optional)

An empty object.

200: The command, and who led when it was asked.

Member Type Required What it is
accepted boolean    
alreadyQueued boolean    
command string    
error string    
error_description string    
errors list    
errors[] string    
href string    
leaderAtRequest object    
leaderAtRequest.node string, or null    
leaderAtRequest.pid integer, or null    
leaderAtRequest.token number, or null    
message string    
ok boolean yes  
run object    
run.abandonedOf string, or null    
run.attempt integer    
run.deferredMs number    
run.dueAt string, or null    
run.durationMs number, or null    
run.endedAt string, or null    
run.fenceAt number    
run.host string    
run.jobId string, or null    
run.nextRunAt string, or null    
run.nextRunInMs number, or null    
run.node string    
run.nodeName string    
run.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
run.pid integer, or null    
run.queuedAt string, or null    
run.queuedAtMs number, or null    
run.ranIn string, or null    
run.realm string, or null    
run.requestedBy string    
run.requestedVia string    
run.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
run.runId string    
run.stale boolean    
run.startedAt string, or null    
run.state string    
run.takenOver boolean    
run.trigger string    
run.why string    
run.worker boolean    
runId string    

202: The answer.

Member Type Required What it is
accepted boolean    
alreadyQueued boolean    
command string    
error string    
error_description string    
errors list    
errors[] string    
href string    
leaderAtRequest object    
leaderAtRequest.node string, or null    
leaderAtRequest.pid integer, or null    
leaderAtRequest.token number, or null    
message string    
ok boolean yes  
run object    
run.abandonedOf string, or null    
run.attempt integer    
run.deferredMs number    
run.dueAt string, or null    
run.durationMs number, or null    
run.endedAt string, or null    
run.fenceAt number    
run.host string    
run.jobId string, or null    
run.nextRunAt string, or null    
run.nextRunInMs number, or null    
run.node string    
run.nodeName string    
run.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
run.pid integer, or null    
run.queuedAt string, or null    
run.queuedAtMs number, or null    
run.ranIn string, or null    
run.realm string, or null    
run.requestedBy string    
run.requestedVia string    
run.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
run.runId string    
run.stale boolean    
run.startedAt string, or null    
run.state string    
run.takenOver boolean    
run.trigger string    
run.why string    
run.worker boolean    
runId string    

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

Member Type Required What it is
accepted boolean    
alreadyQueued boolean    
command string    
error string    
error_description string    
errors list    
errors[] string    
href string    
leaderAtRequest object    
leaderAtRequest.node string, or null    
leaderAtRequest.pid integer, or null    
leaderAtRequest.token number, or null    
message string    
ok boolean yes  
run object    
run.abandonedOf string, or null    
run.attempt integer    
run.deferredMs number    
run.dueAt string, or null    
run.durationMs number, or null    
run.endedAt string, or null    
run.fenceAt number    
run.host string    
run.jobId string, or null    
run.nextRunAt string, or null    
run.nextRunInMs number, or null    
run.node string    
run.nodeName string    
run.params any JSON   A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null. A manual run’s params: the JSON its requester sent, whose members are the job’s own to read, or null.
run.pid integer, or null    
run.queuedAt string, or null    
run.queuedAtMs number, or null    
run.ranIn string, or null    
run.realm string, or null    
run.requestedBy string    
run.requestedVia string    
run.result string, or null   summaryOf(): the job’s answer as text, 500 characters at most.
run.runId string    
run.stale boolean    
run.startedAt string, or null    
run.state string    
run.takenOver boolean    
run.trigger string    
run.why string    
run.worker boolean    
runId string    

GET /admin-api/secrets

getSecrets

Where the key-encryption key and the database password come from, and what the store holding them is doing

The two primordial secrets this service READS and never writes: the key-encryption key everything it seals is sealed under, and the database password. For each — the provider, the location, the field taken out of a JSON value, whether it is sharing the other one’s location, and whether THIS PROCESS has actually read it, with the instant and the error if the last attempt failed. That last one is the fact no settings row can carry: a development-mode service never asks for the key, so a perfectly broken configuration and a working one look identical until the mode changes.

stores is one member per STORE rather than per secret, because two secrets kept in one place share its state. What is in it depends on the provider: file answers the path, mode, owner, mtime and which members the file holds if it is JSON; vault answers the seal status, the health summary, the leader, the certificate this service presents and when it expires, the token the login produced, what that identity may actually do — asked of the store rather than quoted from a policy file — and the engines it can see; aws, gcp and azure publish their metadata against the secret itself.

NO PROBE FETCHES A SECRET VALUE AND NONE IS IN THE REPLY. Every one is a metadata read, and the module they live in deletes a deny-list of member names — value, data, token, id among them — from whatever a provider answers before it leaves.

A PROBE THAT FAILED IS A MEMBER AND NOT AN ABSENCE, with ok: false and, where the store gave one, the HTTP status in status. Here half of them are SUPPOSED to fail: the identity this service holds is bound to two read paths, so a 403 against anything else is the policy working. Each is bounded by keys.storeProbeTimeoutMs and they run in parallel, so an unreachable store costs that bound once.

Mirrors GET /admin/secrets 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 whole report.

Member Type Required What it is
failed list    
failed[] string    
kekHeld boolean    
keySource string    
mode string    
notes map   What each secret is for, by its id.
notes.{key}.heading string    
notes.{key}.rotating string    
notes.{key}.what string    
notes.{key}.without string    
persistingKeys boolean    
productMode boolean    
providers list    
providers[].id string    
providers[].label string    
secrets list    
secrets[].configured boolean    
secrets[].field string    
secrets[].known boolean    
secrets[].label string    
secrets[].lastRead object    
secrets[].lastRead.at string    
secrets[].lastRead.error string    
secrets[].lastRead.label string    
secrets[].lastRead.ok boolean    
secrets[].lastRead.provider string    
secrets[].lastRead.secret string    
secrets[].lastRead.tookMs number    
secrets[].probes list    
secrets[].probes[].data any JSON   What the secret store’s own API answered to a probe, scrubbed of values: its shape is AWS’s, Google’s, Azure’s or Vault’s. What the secret store’s own API answered to a probe, scrubbed of values: its shape is AWS’s, Google’s, Azure’s or Vault’s.
secrets[].probes[].error string    
secrets[].probes[].id string    
secrets[].probes[].ok boolean    
secrets[].probes[].status number    
secrets[].probes[].tookMs number    
secrets[].probes[].what string    
secrets[].provider string    
secrets[].secret string    
secrets[].settings object    
secrets[].settings.field string, or null    
secrets[].settings.location string, or null    
secrets[].settings.provider string, or null    
secrets[].shared boolean    
secrets[].store string, or null    
secrets[].where object    
secrets[].where.authenticates string    
secrets[].where.endpoint string    
secrets[].where.field string    
secrets[].where.from string    
secrets[].where.region string    
secrets[].where.shared boolean    
secrets[].where.vault string    
secrets[].where.wraps string    
stores list    
stores[].key string    
stores[].label string    
stores[].probes list    
stores[].probes[].data any JSON   What the secret store’s own API answered to a probe, scrubbed of values: its shape is AWS’s, Google’s, Azure’s or Vault’s. What the secret store’s own API answered to a probe, scrubbed of values: its shape is AWS’s, Google’s, Azure’s or Vault’s.
stores[].probes[].error string    
stores[].probes[].id string    
stores[].probes[].ok boolean    
stores[].probes[].status number    
stores[].probes[].tookMs number    
stores[].probes[].what string    
stores[].provider string    
stores[].secrets list    
stores[].secrets[] string    
stores[].where string    
timeoutMs number    
what string    

GET /admin-api/status

getStatus

What this service is and how much it has done

The issuer, when it started, and the running totals. The cheapest call here and the one to poll: it takes a snapshot and counts, and reads no list.

Mirrors GET /admin 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 current totals.

Member Type Required What it is
artifactsHeld integer   Assertions, tickets and credentials: everything that is not a JWT.
calls integer   Endpoint calls served.
issuer string    
pages list   The console pages this API mirrors.
pages[] string    
signOnSessions integer   Browser sign-on sessions really held.
startedAt string    
tokensHeld integer    
tokensHeldOnly boolean   True when the token register is read on demand (#820): tokensHeld counts the recent tokens this process holds, not every token issued.
tokensRevoked integer    
uptimeMs number    
usersAuthenticatedHere integer    
usersKnown integer    

GET /admin-api/sts-metadata

getStsMetadata

Every protocol, endpoint and specification this serves

Every protocol family, every endpoint the running router registers (read from the router on each request, so it cannot claim an endpoint that is not there or miss one that is), every specification, and the drift between the router and the descriptions — with the authorization servers this process has served. The same answer as the page’s ?format=json.

Mirrors GET /admin/sts-metadata 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 metadata.

Member Type Required What it is
build object    
build.at string    
build.commit string    
build.number string    
build.release boolean    
build.stamped boolean    
defaultServerId string    
endpoints list    
endpoints[].description string    
endpoints[].documented boolean    
endpoints[].effect string    
endpoints[].group string    
endpoints[].linkable boolean    
endpoints[].methods list    
endpoints[].methods[] string    
endpoints[].name string    
endpoints[].notLinkableBecause string    
endpoints[].path string    
endpoints[].specs list    
endpoints[].specs[] string    
endpoints[].url string    
groupOrder list    
groupOrder[] string    
https boolean    
issuer string    
namedServers list    
namedServers[].autoCreated boolean    
namedServers[].changedAt string    
namedServers[].createdAt string    
namedServers[].description string, or null    
namedServers[].id string    
namedServers[].label string, or null    
namedServers[].memberCount integer    
namedServers[].overrides map   The metadata members this server overrides.
namedServers[].overrides.{key} any JSON   An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines.
namedServers[].removed list    
namedServers[].removed[] string    
namedServers[].seen integer    
namedServers[].seenAt string    
namedServers[].urls object    
namedServers[].urls.authorize string    
namedServers[].urls.oauth string    
namedServers[].urls.oidc string    
namedServers[].urls.token string    
port string, or number, or boolean, or null    
protocols list    
protocols[].endpoints integer    
protocols[].groups list    
protocols[].groups[] string    
protocols[].name string    
protocols[].notAProtocol boolean    
protocols[].sockets string    
protocols[].specs list    
protocols[].specs[] string    
protocols[].what string    
rfc9700 boolean    
rows list    
rows[].coverage string    
rows[].documented boolean    
rows[].effect string    
rows[].group string    
rows[].methods list    
rows[].methods[] string    
rows[].name string    
rows[].path string    
rows[].specs list    
rows[].specs[] string    
rows[].what string    
service string    
specifications list    
specifications[].coverage string    
specifications[].id string    
specifications[].name string    
specifications[].url string    
specifications[].what string    
specifications[].where string    
stalePaths list    
stalePaths[] string    
testDouble boolean    
unclaimedGroups list    
unclaimedGroups[] string    
undocumentedPaths list    
undocumentedPaths[] string    
unknownProtocolGroups list    
unknownProtocolGroups[] string    
unknownProtocolSpecIds list    
unknownProtocolSpecIds[] string    
unknownSpecIds list    
unknownSpecIds[] string    
version string    
wsTrustIssuer string    

GET /admin-api/worker-pools

getWorkerPools

The request and hosted-surface worker pools of this node

Always generatedAt, node, pid (the front process that answered), mainThread (true: drawn on its main thread, which holds the pools), scope (node) and scopeText; then pools, two of them, id request and surface, each with title, module, setting, state (off, not-started, not-dispatching, running or given-up) and stateText saying it in a sentence, maxWorkers (the configured count), initialWorkers (what the pool started with), currentWorkers, busyWorkers, freeWorkers, restarts (forked, crashed — an exit nobody asked for — failedStarts among them, replaced and stopped) and responseTime (answered, averageMs, recentAverageMs, maxMs, dispatch to answer), and its workers — each a worker THREAD of the front process since #364 — (threadId, slot, ready, busy, inFlight, served, upSeconds). restarts.forked counts the threads started. A request pool at the default workers.requestCount of 1 is off where the store cannot coordinate, and stateText says so. There is no post-quantum pool since #363: post-quantum signing and scrypt run on libuv’s thread pool inside each process. Every count is since the process started. THE FIGURES ARE THIS NODE’S at the top level (node names it; never a host or an address). In a cluster, nodes has a section per node — this one live, every other from the snapshot it writes every 15 s, each with name, self, state (live, stale past 45 s, gone from cluster membership, no-snapshot), stateText, ageSeconds and view — and totals sums each pool over the nodes not gone; cluster says whether there is one. answeredBy names the node that answered (#332). A service operation: a realm’s own administrator is refused it.

Mirrors GET /admin/worker-pools on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
node query string   A cluster node’s NAME (cluster.nodeName, node-a, node-b, …), to answer about that node alone: its view at the top, nodes holding its one section. An unknown name is 404 with the names there are (#332).
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 pools.

Member Type Required What it is
answeredBy object    
answeredBy.node string, or null    
answeredBy.pid integer    
cluster object    
cluster.clustered boolean    
cluster.goneRemovedAfterHours number    
cluster.intervalSeconds number    
cluster.readError string, or null    
cluster.staleAfterSeconds number    
cluster.text string    
generatedAt string    
mainThread boolean    
node string, or null    
nodes list    
nodes[].ageSeconds number, or null    
nodes[].name string    
nodes[].self boolean    
nodes[].state string    
nodes[].stateText string    
nodes[].takenAt string, or null    
nodes[].view object    
nodes[].view.generatedAt string    
nodes[].view.mainThread boolean    
nodes[].view.node string, or null    
nodes[].view.pid integer, or null    
nodes[].view.pools list    
nodes[].view.pools[].busyWorkers number    
nodes[].view.pools[].currentWorkers number    
nodes[].view.pools[].freeWorkers number    
nodes[].view.pools[].id string    
nodes[].view.pools[].initialWorkers number    
nodes[].view.pools[].maxWorkers number    
nodes[].view.pools[].module string    
nodes[].view.pools[].prefixes list    
nodes[].view.pools[].prefixes[] string    
nodes[].view.pools[].readyWorkers number    
nodes[].view.pools[].responseTime object    
nodes[].view.pools[].responseTime.answered number    
nodes[].view.pools[].responseTime.averageMs number, or null    
nodes[].view.pools[].responseTime.maxMs number, or null    
nodes[].view.pools[].responseTime.recentAverageMs number, or null    
nodes[].view.pools[].restarts object    
nodes[].view.pools[].restarts.crashed number    
nodes[].view.pools[].restarts.failedStarts number    
nodes[].view.pools[].restarts.forked number    
nodes[].view.pools[].restarts.replaced number    
nodes[].view.pools[].restarts.stopped number    
nodes[].view.pools[].setting string    
nodes[].view.pools[].startedAt string, or null    
nodes[].view.pools[].startingWorkers number    
nodes[].view.pools[].state string    
nodes[].view.pools[].stateText string    
nodes[].view.pools[].title string    
nodes[].view.pools[].workers list    
nodes[].view.pools[].workers[].busy boolean    
nodes[].view.pools[].workers[].inFlight number    
nodes[].view.pools[].workers[].ready boolean    
nodes[].view.pools[].workers[].retiring boolean    
nodes[].view.pools[].workers[].served number    
nodes[].view.pools[].workers[].slot integer, or string, or null    
nodes[].view.pools[].workers[].threadId integer, or string    
nodes[].view.pools[].workers[].upSeconds number, or null    
nodes[].view.scope string    
nodes[].view.scopeText string    
pid integer, or null    
pools list    
pools[].busyWorkers number    
pools[].currentWorkers number    
pools[].freeWorkers number    
pools[].id string    
pools[].initialWorkers number    
pools[].maxWorkers number    
pools[].module string    
pools[].prefixes list    
pools[].prefixes[] string    
pools[].readyWorkers number    
pools[].responseTime object    
pools[].responseTime.answered number    
pools[].responseTime.averageMs number, or null    
pools[].responseTime.maxMs number, or null    
pools[].responseTime.recentAverageMs number, or null    
pools[].restarts object    
pools[].restarts.crashed number    
pools[].restarts.failedStarts number    
pools[].restarts.forked number    
pools[].restarts.replaced number    
pools[].restarts.stopped number    
pools[].setting string    
pools[].startedAt string, or null    
pools[].startingWorkers number    
pools[].state string    
pools[].stateText string    
pools[].title string    
pools[].workers list    
pools[].workers[].busy boolean    
pools[].workers[].inFlight number    
pools[].workers[].ready boolean    
pools[].workers[].retiring boolean    
pools[].workers[].served number    
pools[].workers[].slot integer, or string, or null    
pools[].workers[].threadId integer, or string    
pools[].workers[].upSeconds number, or null    
scope string    
scopeText string    
state string    
totals object    
totals.nodes integer    
totals.nodesCounted integer    
totals.pools list    
totals.pools[].busyWorkers number    
totals.pools[].crashed number    
totals.pools[].currentWorkers number    
totals.pools[].failedStarts number    
totals.pools[].forked number    
totals.pools[].freeWorkers number    
totals.pools[].id string    
totals.pools[].nodesOn number    
totals.pools[].title string    
totals.text string    

404: The answer.

Member Type Required What it is
errors list    
errors[] string    
nodes list   The nodes there are.
nodes[] string    
ok boolean