This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
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 |