This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
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/branding
getBranding
This realm’s sign-in appearance (#717)
Everything Server configuration → Sign-in appearance draws: the layout and the layouts there are, the four colours and the tones derived from them, the contrast of the text, the links and the button text against WCAG 2.2 AA (4.5:1), the display name, the logo’s alternative text and link, the stored logo (its type, sides, size and digest, never its bytes), and the page’s settings. previewUrl and logo.src are in this realm.
Mirrors GET /admin/sign-in-appearance 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 realm’s appearance.
| Member | Type | Required | What it is |
|---|---|---|---|
colours |
object | ||
colours.accent |
string | ||
colours.card |
string | ||
colours.page |
string | ||
colours.text |
string | ||
contrast |
object | ||
contrast.accent |
number | ||
contrast.buttonText |
number | ||
contrast.required |
number | ||
contrast.text |
number | ||
customised |
boolean | ||
derived |
object | ||
derived.border |
string | ||
derived.dim |
string | ||
derived.faint |
string | ||
derived.muted |
string | ||
derived.onAccent |
string | ||
derived.rule |
string | ||
displayName |
string | ||
layout |
string | ||
layouts |
list | ||
layouts[] |
string | ||
logo |
object | ||
logo.bytes |
number | ||
logo.height |
number | ||
logo.sha256 |
string | ||
logo.src |
string | ||
logo.type |
string | ||
logo.updatedAt |
string | ||
logo.updatedBy |
string | ||
logo.url |
string | ||
logo.width |
number | ||
logoAlt |
string | ||
logoLinkUrl |
string | ||
logoMaxBytes |
number | ||
preview |
string | ||
previewUrl |
string | ||
realm |
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 |
POST /admin-api/branding/logo
uploadBrandingLogo
Upload this realm’s sign-in logo
The request body is the image itself: a PNG, a JPEG or a WebP, which the bytes decide whatever Content-Type says. Each side 16 to 2048 pixels, at most branding.logoMaxBytes. It replaces the logo the realm had. A logo needs alternative text: send it as alt, or set branding.logoAlt first. Served at this realm’s /web/branding/logo. Audited, with its digest and never its bytes.
Mirrors POST /admin/sign-in-appearance on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
alt |
query | string | The alternative text, written to branding.logoAlt with the image. | |
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
As application/octet-stream.
As image/jpeg.
As image/png.
As image/webp.
200: The stored logo, in logo.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
logo |
object | ||
logo.bytes |
number | ||
logo.height |
number | ||
logo.sha256 |
string | ||
logo.src |
string | ||
logo.type |
string | ||
logo.updatedAt |
string | ||
logo.updatedBy |
string | ||
logo.url |
string | ||
logo.width |
number | ||
message |
string | ||
ok |
boolean | yes | |
status |
number |
400: The operation was refused; errors says why and nothing was handed over.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
logo |
object | ||
logo.bytes |
number | ||
logo.height |
number | ||
logo.sha256 |
string | ||
logo.src |
string | ||
logo.type |
string | ||
logo.updatedAt |
string | ||
logo.updatedBy |
string | ||
logo.url |
string | ||
logo.width |
number | ||
message |
string | ||
ok |
boolean | yes | |
status |
number |
413: Larger than branding.logoMaxBytes.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
logo |
object | ||
logo.bytes |
number | ||
logo.height |
number | ||
logo.sha256 |
string | ||
logo.src |
string | ||
logo.type |
string | ||
logo.updatedAt |
string | ||
logo.updatedBy |
string | ||
logo.url |
string | ||
logo.width |
number | ||
message |
string | ||
ok |
boolean | yes | |
status |
number |
415: Not a PNG, a JPEG or a WebP, by its bytes.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
logo |
object | ||
logo.bytes |
number | ||
logo.height |
number | ||
logo.sha256 |
string | ||
logo.src |
string | ||
logo.type |
string | ||
logo.updatedAt |
string | ||
logo.updatedBy |
string | ||
logo.url |
string | ||
logo.width |
number | ||
message |
string | ||
ok |
boolean | yes | |
status |
number |
POST /admin-api/branding/remove-logo
removeBrandingLogo
Remove this realm’s sign-in logo
The sign-in pages show no logo afterwards. The alternative text stays, so the next upload needs none. Audited where there was a logo to remove.
Mirrors POST /admin/sign-in-appearance 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: removed: whether there was one.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
removed |
boolean | ||
saved |
list | ||
saved[] |
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 | |
removed |
boolean | ||
saved |
list | ||
saved[] |
string |
POST /admin-api/branding/save
saveBranding
Change this realm’s sign-in appearance
Writes the branding.* settings named, in this realm: the default realm’s are the process’s overrides, a realm’s are its own, as POST /admin-api/config/set would write them. They are judged TOGETHER, so a text colour and a card colour that pass only as a pair are taken as a pair, and nothing is written when any is refused: a colour that is not one, text or links below WCAG 2.2 AA (4.5:1) against the card, a link that is not https, an empty alternative text while a logo is set. A key that is not one of these eight is refused by name. branding.logoMaxBytes is the process’s, set with /config/set.
Mirrors POST /admin/sign-in-appearance 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 |
|---|---|---|---|
branding.accentColor |
string | Buttons, links and focus rings, #rgb or #rrggbb; stored as six lower-case digits. |
|
branding.cardColor |
string | The card, #rgb or #rrggbb; stored as six lower-case digits. |
|
branding.displayName |
string | Shown beside the logo and in the document title. Text, never markup, and never translated. Empty for none. | |
branding.layout |
one of centered, split, banner |
centered (the card alone), split (a brand panel beside the card) or banner (a band above it). | |
branding.logoAlt |
string | The logo’s alternative text. Required while a logo is set. | |
branding.logoLinkUrl |
string | An absolute https URL the logo links to, or empty for no link. | |
branding.pageColor |
string | The page behind the card, #rgb or #rrggbb; stored as six lower-case digits. |
|
branding.textColor |
string | The text on the card, #rgb or #rrggbb; stored as six lower-case digits. |
200: The keys written, in saved.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
removed |
boolean | ||
saved |
list | ||
saved[] |
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 | |
removed |
boolean | ||
saved |
list | ||
saved[] |
string |
GET /admin-api/config
getConfig
Every setting this service has, and where each value came from
Every setting, grouped by protocol, each with its effective value and the SOURCE of that value: a runtime override, an environment variable, the appconfig file CONFIG_FILE names, or env/defaults.js under it. The source is the part that was not answerable before this resource existed — the four are indistinguishable once a value has been read, and the question “why is the issuer that?” used to be a grep. There is no fifth source: a setting with a value in none of them stops this service from STARTING rather than falling back to a constant in a module.
It also says which settings can be CHANGED while the service runs. The ones that cannot were consumed at startup — a bound socket, the TLS certificate’s names, the Kerberos principal database and its long-term keys, the directory’s base DN — and each carries the reason.
Mirrors GET /admin/config 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 table.
| Member | Type | Required | What it is |
|---|---|---|---|
configFile |
string, or null | The CONFIG_FILE this process was started with, which is the file to edit to make a change survive a restart. Nothing here ever writes to it. | |
defaultsFile |
string | The DEFAULT appconfig file, which configFile is unioned on top of key by key with the operator’s value winning. A setting whose source is defaults came from here. |
|
editableCount |
integer | How many of them POST /config/set will take. The rest are restart-only and say why in restartReason. |
|
groups |
list | In the order config.js declares them, which is the order the console renders its sections. |
|
groups[] |
object | One group’s settings. | |
groups[].group |
string | ||
groups[].settings |
list | ||
groups[].settings[] |
object | One setting: what it is, what it is set to, and where that came from. | |
groups[].settings[].appconfigPath |
string | ||
groups[].settings[].csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
groups[].settings[].csvValueNotes.{key} |
string | ||
groups[].settings[].csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
groups[].settings[].csvValues[] |
string | ||
groups[].settings[].default |
list, or string, or number, or boolean, or null | ||
groups[].settings[].default[] |
string, or number, or boolean | ||
groups[].settings[].description |
string | What it does and why the default is the default. | |
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. |
|
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. |
|
groups[].settings[].enumValues |
list | Present on enum settings only. |
|
groups[].settings[].enumValues[] |
string | ||
groups[].settings[].env |
string | Its environment variable. | |
groups[].settings[].group |
string | The protocol it belongs to, and the console’s section heading. | |
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. |
|
groups[].settings[].label |
string | ||
groups[].settings[].masked |
boolean | Present, true, when a sensitive value here was replaced. | |
groups[].settings[].max |
number | The highest value it will take. | |
groups[].settings[].min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
groups[].settings[].ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
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. |
|
groups[].settings[].realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
groups[].settings[].restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
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. |
|
groups[].settings[].selectAll.aloneWhileOn |
list | ||
groups[].settings[].selectAll.aloneWhileOn[].canBeOn |
boolean | ||
groups[].settings[].selectAll.aloneWhileOn[].on |
boolean | ||
groups[].settings[].selectAll.aloneWhileOn[].setting |
string | ||
groups[].settings[].selectAll.aloneWhileOn[].values |
list | ||
groups[].settings[].selectAll.aloneWhileOn[].values[] |
object | Nested deeper than this page draws. | |
groups[].settings[].selectAll.onlyWhileOn |
list | ||
groups[].settings[].selectAll.onlyWhileOn[].canBeOn |
boolean | ||
groups[].settings[].selectAll.onlyWhileOn[].on |
boolean | ||
groups[].settings[].selectAll.onlyWhileOn[].setting |
string | ||
groups[].settings[].selectAll.onlyWhileOn[].values |
list | ||
groups[].settings[].selectAll.onlyWhileOn[].values[] |
object | Nested deeper than this page draws. | |
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. |
|
groups[].settings[].step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
groups[].settings[].text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
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). |
|
groups[].settings[].value |
list, or string, or number, or boolean, or null | ||
groups[].settings[].value[] |
string, or number, or boolean | ||
homeProblems |
list | Empty, and reported rather than left implicit. A sentence here means a setting group exists that no console page draws. | |
homeProblems[] |
string | ||
homes |
list | WHERE EACH GROUP IS EDITED: every group is drawn on the console page for the protocol it configures, so a caller can send a person to the right page. Every one of those forms posts to the same four actions. | |
homes[] |
object | One group, and the page or pages that draw it. | |
homes[].group |
string | ||
homes[].labels |
list | The pages’ console labels, in the same order. | |
homes[].labels[] |
string | ||
homes[].pages |
list | ||
homes[].pages[] |
string | ||
overridden |
list | The keys with a runtime override in force. Empty on a freshly started service, and emptied again by POST /config/reset-all. | |
overridden[] |
string | ||
realm |
string | The realm this was read in. | |
realmSettings |
list | The keys that realm holds a value of its own for. | |
realmSettings[] |
string | ||
settingCount |
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 |
GET /admin-api/config-dump
getConfigDump
Every configuration parameter, with sensitive values masked
The configuration of this running instance as one document: every parameter in settings with its effective value and source and, in the default realm, what each other trust realm sets in realms. Under a realm’s prefix it is that realm’s effective parameters. Every sensitive value is replaced by masking.mask before it is answered. Directory objects are not part of it. Each read is audited as admin.config-dump.
Mirrors GET /admin/config-dump 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 dump.
| Member | Type | Required | What it is |
|---|---|---|---|
configFile |
string, or null | ||
defaultsFile |
string | ||
format |
string | The format of this document. | |
generatedAt |
string | ||
masking |
object | ||
masking.mask |
string | The text that replaces a sensitive value. | |
masking.maskedValues |
integer | How many parameters had a value replaced. | |
realm |
string | The realm settings was read in. |
|
realms |
list | Every other realm. Empty under a realm’s prefix. | |
realms[].id |
string | ||
realms[].settings |
list | The parameters this realm sets itself. | |
realms[].settings[] |
object | One parameter, its sensitive values masked. | |
realms[].settings[].default |
list, or string, or number, or boolean, or null | ||
realms[].settings[].default[] |
string, or number, or boolean | ||
realms[].settings[].editable |
boolean | ||
realms[].settings[].env |
string | The environment variable that sets it. | |
realms[].settings[].group |
string | ||
realms[].settings[].key |
string | The parameter’s dot path. | |
realms[].settings[].masked |
boolean | Present, true, when a sensitive value was replaced. | |
realms[].settings[].overridden |
boolean | ||
realms[].settings[].source |
string | Where the effective value came from, as GET /config says. |
|
realms[].settings[].type |
string | ||
realms[].settings[].value |
list, or string, or number, or boolean, or null | ||
realms[].settings[].value[] |
string, or number, or boolean | ||
scope |
one of service, realm |
service from the default realm, realm under a realm’s prefix. |
|
settingCount |
integer | ||
settings |
list | Every parameter, in table order. | |
settings[] |
object | One parameter, its sensitive values masked. | |
settings[].default |
list, or string, or number, or boolean, or null | ||
settings[].default[] |
string, or number, or boolean | ||
settings[].editable |
boolean | ||
settings[].env |
string | The environment variable that sets it. | |
settings[].group |
string | ||
settings[].key |
string | The parameter’s dot path. | |
settings[].masked |
boolean | Present, true, when a sensitive value was replaced. | |
settings[].overridden |
boolean | ||
settings[].source |
string | Where the effective value came from, as GET /config says. |
|
settings[].type |
string | ||
settings[].value |
list, or string, or number, or boolean, or null | ||
settings[].value[] |
string, or number, or boolean | ||
version |
string | This service’s version. |
POST /admin-api/config/reset
resetSetting
Drop one runtime override
The setting falls back to whatever it would have used had nothing ever been set here — its environment variable, the appconfig file, or env/defaults.js. A setting with no override is refused rather than treated as already done, because the two are different facts and a caller that misspelt a key would otherwise be told it succeeded.
Mirrors POST /admin/config, POST /admin/xacml#xacml-tab-settings and POST /admin/xacml#xacml-tab-authzen 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 |
|---|---|---|---|
key |
string | yes |
200: The setting as it now stands, in setting.
| 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 | ||
setting |
object | One setting: what it is, what it is set to, and where that came from. | |
setting.appconfigPath |
string | ||
setting.csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
setting.csvValueNotes.{key} |
string | ||
setting.csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
setting.csvValues[] |
string | ||
setting.default |
list, or string, or number, or boolean, or null | ||
setting.default[] |
string, or number, or boolean | ||
setting.description |
string | What it does and why the default is the default. | |
setting.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. |
|
setting.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. |
|
setting.enumValues |
list | Present on enum settings only. |
|
setting.enumValues[] |
string | ||
setting.env |
string | Its environment variable. | |
setting.group |
string | The protocol it belongs to, and the console’s section heading. | |
setting.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. |
|
setting.label |
string | ||
setting.masked |
boolean | Present, true, when a sensitive value here was replaced. | |
setting.max |
number | The highest value it will take. | |
setting.min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
setting.ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
setting.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. |
|
setting.realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
setting.restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
setting.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. |
|
setting.selectAll.aloneWhileOn |
list | ||
setting.selectAll.aloneWhileOn[].canBeOn |
boolean | ||
setting.selectAll.aloneWhileOn[].on |
boolean | ||
setting.selectAll.aloneWhileOn[].setting |
string | ||
setting.selectAll.aloneWhileOn[].values |
list | ||
setting.selectAll.aloneWhileOn[].values[] |
string | ||
setting.selectAll.onlyWhileOn |
list | ||
setting.selectAll.onlyWhileOn[].canBeOn |
boolean | ||
setting.selectAll.onlyWhileOn[].on |
boolean | ||
setting.selectAll.onlyWhileOn[].setting |
string | ||
setting.selectAll.onlyWhileOn[].values |
list | ||
setting.selectAll.onlyWhileOn[].values[] |
string | ||
setting.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. |
|
setting.step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
setting.text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
setting.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). |
|
setting.value |
list, or string, or number, or boolean, or null | ||
setting.value[] |
string, or number, or 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 | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
realm |
string, or null | ||
setting |
object | One setting: what it is, what it is set to, and where that came from. | |
setting.appconfigPath |
string | ||
setting.csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
setting.csvValueNotes.{key} |
string | ||
setting.csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
setting.csvValues[] |
string | ||
setting.default |
list, or string, or number, or boolean, or null | ||
setting.default[] |
string, or number, or boolean | ||
setting.description |
string | What it does and why the default is the default. | |
setting.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. |
|
setting.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. |
|
setting.enumValues |
list | Present on enum settings only. |
|
setting.enumValues[] |
string | ||
setting.env |
string | Its environment variable. | |
setting.group |
string | The protocol it belongs to, and the console’s section heading. | |
setting.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. |
|
setting.label |
string | ||
setting.masked |
boolean | Present, true, when a sensitive value here was replaced. | |
setting.max |
number | The highest value it will take. | |
setting.min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
setting.ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
setting.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. |
|
setting.realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
setting.restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
setting.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. |
|
setting.selectAll.aloneWhileOn |
list | ||
setting.selectAll.aloneWhileOn[].canBeOn |
boolean | ||
setting.selectAll.aloneWhileOn[].on |
boolean | ||
setting.selectAll.aloneWhileOn[].setting |
string | ||
setting.selectAll.aloneWhileOn[].values |
list | ||
setting.selectAll.aloneWhileOn[].values[] |
string | ||
setting.selectAll.onlyWhileOn |
list | ||
setting.selectAll.onlyWhileOn[].canBeOn |
boolean | ||
setting.selectAll.onlyWhileOn[].on |
boolean | ||
setting.selectAll.onlyWhileOn[].setting |
string | ||
setting.selectAll.onlyWhileOn[].values |
list | ||
setting.selectAll.onlyWhileOn[].values[] |
string | ||
setting.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. |
|
setting.step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
setting.text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
setting.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). |
|
setting.value |
list, or string, or number, or boolean, or null | ||
setting.value[] |
string, or number, or boolean |
POST /admin-api/config/reset-all
resetAllSettings
Drop every runtime override
Returns the whole service to the configuration it started with, without restarting it. This is what a test should call to put the service back: the service’s admin state survives between jobs, so a setting left changed here changes what every later job sees.
Mirrors POST /admin/config, POST /admin/xacml#xacml-tab-settings and POST /admin/xacml#xacml-tab-authzen 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 keys that were cleared, in cleared.
| Member | Type | Required | What it is |
|---|---|---|---|
cleared |
list | ||
cleared[] |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
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 |
|---|---|---|---|
cleared |
list | ||
cleared[] |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
realm |
string, or null |
POST /admin-api/config/set
setSetting
Change one setting
A RUNTIME OVERRIDE — the top of config.js’s five layers. Whether it outlives the process is persistence.appconfig: with a persistent store (persistence.mode ldif or postgres) it is written down and re-applied at the next start through this same function, which is why it adds no sixth layer, and only with persistence.mode=memory is it gone on restart. A write made while a non-default realm is ambient lands on that realm and is written down with the realm row, so persistence.realms decides it there. The reply’s message says which. See GET /admin-api/persistence.
NOTHING HERE WRITES TO THE APPCONFIG FILE in either mode, and that is deliberate rather than unfinished: a service that edited a file checked into a repository would leave a test’s forgotten change behind permanently. The durable copy goes to the persistent store, which is not a place anything is checked in from.
The change applies to the next token, assertion, ticket or search. Nothing already issued changes, because a token is a signed document.
A setting whose editable is false is REFUSED with the reason rather than accepted, and a value that does not fit the setting’s type is refused by name.
Mirrors POST /admin/config, POST /admin/xacml#xacml-tab-settings and POST /admin/xacml#xacml-tab-authzen 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 |
|---|---|---|---|
key |
string | yes | The dot path, as GET /admin-api/config lists it. |
value |
any JSON | yes | A string is always accepted and is coerced to the setting’s type, so the environment spelling works here too; a JSON number, boolean or array of strings is accepted where the type takes one. |
200: The setting as it now stands, in setting.
| 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 | ||
setting |
object | One setting: what it is, what it is set to, and where that came from. | |
setting.appconfigPath |
string | ||
setting.csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
setting.csvValueNotes.{key} |
string | ||
setting.csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
setting.csvValues[] |
string | ||
setting.default |
list, or string, or number, or boolean, or null | ||
setting.default[] |
string, or number, or boolean | ||
setting.description |
string | What it does and why the default is the default. | |
setting.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. |
|
setting.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. |
|
setting.enumValues |
list | Present on enum settings only. |
|
setting.enumValues[] |
string | ||
setting.env |
string | Its environment variable. | |
setting.group |
string | The protocol it belongs to, and the console’s section heading. | |
setting.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. |
|
setting.label |
string | ||
setting.masked |
boolean | Present, true, when a sensitive value here was replaced. | |
setting.max |
number | The highest value it will take. | |
setting.min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
setting.ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
setting.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. |
|
setting.realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
setting.restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
setting.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. |
|
setting.selectAll.aloneWhileOn |
list | ||
setting.selectAll.aloneWhileOn[].canBeOn |
boolean | ||
setting.selectAll.aloneWhileOn[].on |
boolean | ||
setting.selectAll.aloneWhileOn[].setting |
string | ||
setting.selectAll.aloneWhileOn[].values |
list | ||
setting.selectAll.aloneWhileOn[].values[] |
string | ||
setting.selectAll.onlyWhileOn |
list | ||
setting.selectAll.onlyWhileOn[].canBeOn |
boolean | ||
setting.selectAll.onlyWhileOn[].on |
boolean | ||
setting.selectAll.onlyWhileOn[].setting |
string | ||
setting.selectAll.onlyWhileOn[].values |
list | ||
setting.selectAll.onlyWhileOn[].values[] |
string | ||
setting.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. |
|
setting.step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
setting.text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
setting.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). |
|
setting.value |
list, or string, or number, or boolean, or null | ||
setting.value[] |
string, or number, or 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 | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
realm |
string, or null | ||
setting |
object | One setting: what it is, what it is set to, and where that came from. | |
setting.appconfigPath |
string | ||
setting.csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
setting.csvValueNotes.{key} |
string | ||
setting.csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
setting.csvValues[] |
string | ||
setting.default |
list, or string, or number, or boolean, or null | ||
setting.default[] |
string, or number, or boolean | ||
setting.description |
string | What it does and why the default is the default. | |
setting.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. |
|
setting.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. |
|
setting.enumValues |
list | Present on enum settings only. |
|
setting.enumValues[] |
string | ||
setting.env |
string | Its environment variable. | |
setting.group |
string | The protocol it belongs to, and the console’s section heading. | |
setting.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. |
|
setting.label |
string | ||
setting.masked |
boolean | Present, true, when a sensitive value here was replaced. | |
setting.max |
number | The highest value it will take. | |
setting.min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
setting.ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
setting.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. |
|
setting.realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
setting.restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
setting.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. |
|
setting.selectAll.aloneWhileOn |
list | ||
setting.selectAll.aloneWhileOn[].canBeOn |
boolean | ||
setting.selectAll.aloneWhileOn[].on |
boolean | ||
setting.selectAll.aloneWhileOn[].setting |
string | ||
setting.selectAll.aloneWhileOn[].values |
list | ||
setting.selectAll.aloneWhileOn[].values[] |
string | ||
setting.selectAll.onlyWhileOn |
list | ||
setting.selectAll.onlyWhileOn[].canBeOn |
boolean | ||
setting.selectAll.onlyWhileOn[].on |
boolean | ||
setting.selectAll.onlyWhileOn[].setting |
string | ||
setting.selectAll.onlyWhileOn[].values |
list | ||
setting.selectAll.onlyWhileOn[].values[] |
string | ||
setting.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. |
|
setting.step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
setting.text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
setting.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). |
|
setting.value |
list, or string, or number, or boolean, or null | ||
setting.value[] |
string, or number, or boolean |
POST /admin-api/config/set-many
setSettings
Change a whole section at once
What the console’s per-section Save posts, and it is not a convenience: a section is how a person changes configuration, and one call per field would make a partly-applied section the ordinary outcome of a mistake in any one of them.
ALL-OR-NOTHING. Every value is checked before any is written, so a body with one bad field changes nothing and names it. A key this service does not know is ignored rather than refused, because a form posts fields this resource never declared; applied says which were taken and changed which actually differed from what was already in force.
Mirrors POST /admin/config, POST /admin/xacml#xacml-tab-settings and POST /admin/xacml#xacml-tab-authzen 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
An empty object.
200: What was applied, in applied, and what actually changed, in changed.
| Member | Type | Required | What it is |
|---|---|---|---|
applied |
list | ||
applied[] |
string | ||
changed |
list | ||
changed[] |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
settings |
list | ||
settings[] |
object | One setting: what it is, what it is set to, and where that came from. | |
settings[].appconfigPath |
string | ||
settings[].csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
settings[].csvValueNotes.{key} |
string | ||
settings[].csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
settings[].csvValues[] |
string | ||
settings[].default |
list, or string, or number, or boolean, or null | ||
settings[].default[] |
string, or number, or boolean | ||
settings[].description |
string | What it does and why the default is the default. | |
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[].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[].enumValues |
list | Present on enum settings only. |
|
settings[].enumValues[] |
string | ||
settings[].env |
string | Its environment variable. | |
settings[].group |
string | The protocol it belongs to, and the console’s section heading. | |
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[].label |
string | ||
settings[].masked |
boolean | Present, true, when a sensitive value here was replaced. | |
settings[].max |
number | The highest value it will take. | |
settings[].min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
settings[].ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
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[].realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
settings[].restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
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[].selectAll.aloneWhileOn |
list | ||
settings[].selectAll.aloneWhileOn[].canBeOn |
boolean | ||
settings[].selectAll.aloneWhileOn[].on |
boolean | ||
settings[].selectAll.aloneWhileOn[].setting |
string | ||
settings[].selectAll.aloneWhileOn[].values |
list | ||
settings[].selectAll.aloneWhileOn[].values[] |
string | ||
settings[].selectAll.onlyWhileOn |
list | ||
settings[].selectAll.onlyWhileOn[].canBeOn |
boolean | ||
settings[].selectAll.onlyWhileOn[].on |
boolean | ||
settings[].selectAll.onlyWhileOn[].setting |
string | ||
settings[].selectAll.onlyWhileOn[].values |
list | ||
settings[].selectAll.onlyWhileOn[].values[] |
string | ||
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[].step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
settings[].text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
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[].value |
list, or string, or number, or boolean, or null | ||
settings[].value[] |
string, or number, or boolean |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
applied |
list | ||
applied[] |
string | ||
changed |
list | ||
changed[] |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
settings |
list | ||
settings[] |
object | One setting: what it is, what it is set to, and where that came from. | |
settings[].appconfigPath |
string | ||
settings[].csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
settings[].csvValueNotes.{key} |
string | ||
settings[].csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
settings[].csvValues[] |
string | ||
settings[].default |
list, or string, or number, or boolean, or null | ||
settings[].default[] |
string, or number, or boolean | ||
settings[].description |
string | What it does and why the default is the default. | |
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[].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[].enumValues |
list | Present on enum settings only. |
|
settings[].enumValues[] |
string | ||
settings[].env |
string | Its environment variable. | |
settings[].group |
string | The protocol it belongs to, and the console’s section heading. | |
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[].label |
string | ||
settings[].masked |
boolean | Present, true, when a sensitive value here was replaced. | |
settings[].max |
number | The highest value it will take. | |
settings[].min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
settings[].ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
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[].realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
settings[].restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
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[].selectAll.aloneWhileOn |
list | ||
settings[].selectAll.aloneWhileOn[].canBeOn |
boolean | ||
settings[].selectAll.aloneWhileOn[].on |
boolean | ||
settings[].selectAll.aloneWhileOn[].setting |
string | ||
settings[].selectAll.aloneWhileOn[].values |
list | ||
settings[].selectAll.aloneWhileOn[].values[] |
string | ||
settings[].selectAll.onlyWhileOn |
list | ||
settings[].selectAll.onlyWhileOn[].canBeOn |
boolean | ||
settings[].selectAll.onlyWhileOn[].on |
boolean | ||
settings[].selectAll.onlyWhileOn[].setting |
string | ||
settings[].selectAll.onlyWhileOn[].values |
list | ||
settings[].selectAll.onlyWhileOn[].values[] |
string | ||
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[].step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
settings[].text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
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[].value |
list, or string, or number, or boolean, or null | ||
settings[].value[] |
string, or number, or boolean |