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/geolocation
getGeolocation
Where the realm’s people signed in from
The realm’s people counted by place, from what risk scoring recorded: the total of the place asked for (the world total beside it), the seven continents, the countries (every one at the world level, a continent’s with continent, one with country) and, with country, its cities with their coordinates. Each place has people (distinct, counted at that level, never summed), signIns and lastAt. A place with fewer people than minimumCount (risk.geoMinimumCount) has people and signIns null and suppressed true, and such a city is left out and counted in hidden. unknown is where no dataset placed the address; countryOnly, in a country, where only its country was known. window live counts the live sessions (liveSessions), each at its latest assessment.
Mirrors GET /admin/geolocation on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
window |
query | one of live, 24h, 7d, 30d |
Live sessions, or everybody over a span; live when absent. | |
continent |
query | one of africa, antarctica, asia, europe, north-america, oceania, south-america |
One continent’s countries. | |
country |
query | string | One country (ISO 3166-1 alpha-2) and its cities. | |
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 counts by place.
| Member | Type | Required | What it is |
|---|---|---|---|
attributions |
list | ||
attributions[].licence |
string, or null | ||
attributions[].licenceUrl |
string, or null | ||
attributions[].modified |
string | ||
attributions[].provider |
string | ||
attributions[].text |
string | ||
attributions[].url |
string, or null | ||
cities |
list | ||
cities[].city |
string | ||
cities[].lastAt |
number | ||
cities[].latitude |
number, or null | ||
cities[].longitude |
number, or null | ||
cities[].people |
number | ||
cities[].signIns |
number | ||
cities[].subdivision |
string, or null | ||
continent |
object | ||
continent.continent |
string | ||
continent.name |
string | ||
continents |
list | ||
continents[].continent |
string | ||
continents[].lastAt |
number | ||
continents[].name |
string | ||
continents[].people |
number, or null | ||
continents[].signIns |
number, or null | ||
continents[].suppressed |
boolean | ||
countries |
list | ||
countries[].continent |
string, or null | ||
countries[].iso |
string | ||
countries[].lastAt |
number | ||
countries[].name |
string | ||
countries[].onMap |
boolean | ||
countries[].people |
number, or null | ||
countries[].signIns |
number, or null | ||
countries[].suppressed |
boolean | ||
country |
object | ||
country.iso |
string | ||
country.name |
string | ||
countryOnly |
object | ||
countryOnly.lastAt |
number | ||
countryOnly.people |
number, or null | ||
countryOnly.signIns |
number, or null | ||
countryOnly.suppressed |
boolean | ||
database |
boolean | ||
datasets |
list | ||
datasets[].dataset |
string | ||
datasets[].state |
string | ||
datasets[].title |
string | ||
datasets[].version |
string | ||
drawing |
object | ||
drawing.legend |
list | ||
drawing.legend[].colour |
string | ||
drawing.legend[].from |
number | ||
drawing.legend[].to |
number | ||
drawing.picture |
object | ||
drawing.picture.height |
number | ||
drawing.picture.svg |
string | ||
drawing.picture.width |
number | ||
hidden |
object | ||
hidden.cities |
number | ||
hidden.signIns |
number | ||
level |
string | ||
liveSessions |
number, or null | ||
minimumCount |
number | ||
noDataColour |
string | ||
ok |
boolean | ||
outlines |
object | ||
outlines.generatedBy |
string | ||
outlines.inputSha256 |
string | ||
outlines.license |
string | ||
outlines.source |
string | ||
outlines.upstream |
string | ||
outlines.url |
string | ||
realm |
string | ||
since |
number | ||
total |
object | ||
total.lastAt |
number | ||
total.people |
number, or null | ||
total.signIns |
number, or null | ||
total.suppressed |
boolean | ||
unknown |
object | ||
unknown.lastAt |
number | ||
unknown.people |
number, or null | ||
unknown.signIns |
number, or null | ||
unknown.suppressed |
boolean | ||
window |
string | ||
windows |
list | ||
windows[] |
string | ||
world |
object | ||
world.lastAt |
number | ||
world.people |
number, or null | ||
world.signIns |
number, or null | ||
world.suppressed |
boolean |
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/risk
getRisk
The risk datasets, a lookup, and the refused passwords
Which store holds the risk data (the database, or this process where there is none); every dataset in datasets with its state (active, stale or empty), active and previous version, publication date, row count, provider attribution and every recorded versions row (refused ones with their refusal); the formats a file may be in; with address, what the active datasets say about it in lookup (geo, asn, lists, the datasets versions that answered and any stale ones left out); with authenticator, what the active FIDO MDS3 BLOB says about that key in authenticatorLookup (keyKind, key, listed, why when it is not, version, stale, and the listed model: description, protocolFamily, certificationLevel, latestStatus, compromised, statusReports, metadataStatement); and a page of the realm’s refused passwords in failures — a subject or a name’s digest, the door, the network prefix, the ASN and the code, never an address. A page of the realm’s assessed sign-ins in assessments ({ total, rows }, the last 7 days, newest first; each row’s first signal is the model’s, with its factors, the user term’s terms, and unknown, the levels whose lookup found nothing — asn, country, browser, os, device — which the model counts as unseen) and of its people by current standing in subjects, each with its assessmentsPaging / subjectsPaging. Every row naming a person’s subject also carries their username (‘’ when the directory no longer holds them).
Mirrors GET /admin/risk on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
address |
query | string | An IPv4 or IPv6 address to look up. | |
authenticator |
query | string | An AAGUID, an AAID (XXXX#XXXX) or an attestation certificate key identifier (40 hex digits) to look up in the FIDO metadata (#1080). |
|
level |
query | string | Only the assessments at this level. | |
subject |
query | string | Only this person’s assessments. | |
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. | |
assessmentsPage |
query | integer | Which page of assessments to return, answered by assessmentsPaging. The sign-ins assessed in the last 7 days, newest first, 50 by default. |
|
subjectsPage |
query | integer | Which page of subjects to return, answered by subjectsPaging. The realm’s people by current standing, highest score first, twenty-five by default. |
|
failuresPage |
query | integer | Which page of failures to return, answered by failuresPaging. The refused passwords of the last 7 days, newest first, fifty by default (#313). |
|
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 datasets, the lookup, the failures, the assessments and the standings.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptances |
list | ||
acceptances[].acceptedAt |
number | ||
acceptances[].acceptedBy |
string | ||
acceptances[].acceptedVia |
string | ||
acceptances[].deployment |
string | ||
acceptances[].id |
string, or number | ||
acceptances[].pageDigest |
string | ||
acceptances[].provider |
string | ||
acceptances[].termsDigest |
string | ||
acceptances[].termsText |
string | ||
assessments |
object | ||
assessments.rows |
list | ||
assessments.rows[].aaguid |
string, or null | ||
assessments.rows[].accuracyKm |
number | ||
assessments.rows[].addressPrefix |
string, or null | ||
assessments.rows[].asOrg |
string, or null | ||
assessments.rows[].asn |
number | ||
assessments.rows[].at |
number | ||
assessments.rows[].authenticatorCert |
string, or null | ||
assessments.rows[].backupEligible |
boolean, or null | ||
assessments.rows[].backupState |
boolean, or null | ||
assessments.rows[].bot |
boolean, or null | ||
assessments.rows[].city |
string, or null | ||
assessments.rows[].clientId |
string, or null | ||
assessments.rows[].country |
string, or null | ||
assessments.rows[].credentialHash |
string, or null | ||
assessments.rows[].credentialKind |
string, or null | ||
assessments.rows[].datasets |
map | The version of each dataset read, and stale and attributions beside them. |
|
assessments.rows[].datasets.{key} |
list, or string | ||
assessments.rows[].datasets.{key}[] |
object, or string | ||
assessments.rows[].datasets.{key}[].licence |
object | Nested deeper than this page draws. | |
assessments.rows[].datasets.{key}[].licenceUrl |
object | Nested deeper than this page draws. | |
assessments.rows[].datasets.{key}[].modified |
object | Nested deeper than this page draws. | |
assessments.rows[].datasets.{key}[].provider |
object | Nested deeper than this page draws. | |
assessments.rows[].datasets.{key}[].text |
object | Nested deeper than this page draws. | |
assessments.rows[].datasets.{key}[].url |
object | Nested deeper than this page draws. | |
assessments.rows[].decision |
string, or null | ||
assessments.rows[].door |
string | ||
assessments.rows[].feedback |
string, or null | ||
assessments.rows[].feedbackAt |
number | ||
assessments.rows[].id |
string | ||
assessments.rows[].ipLists |
list | ||
assessments.rows[].ipLists[] |
string | ||
assessments.rows[].ja4 |
string, or null | ||
assessments.rows[].latitude |
number, or null | ||
assessments.rows[].level |
string | ||
assessments.rows[].longitude |
number, or null | ||
assessments.rows[].phase |
string | ||
assessments.rows[].policyId |
string, or null | ||
assessments.rows[].realm |
string | ||
assessments.rows[].score |
number, or null | ||
assessments.rows[].sessionId |
string, or null | ||
assessments.rows[].signals |
list | ||
assessments.rows[].signals[].capped |
string | ||
assessments.rows[].signals[].device |
object | ||
assessments.rows[].signals[].device.attestation |
string | ||
assessments.rows[].signals[].device.compliance |
string | ||
assessments.rows[].signals[].device.id |
string | ||
assessments.rows[].signals[].device.own |
boolean | ||
assessments.rows[].signals[].device.status |
string | ||
assessments.rows[].signals[].device.via |
string | ||
assessments.rows[].signals[].evidence |
string, or null | ||
assessments.rows[].signals[].factor |
number, or null | ||
assessments.rows[].signals[].factors |
map | Per level of the model. | |
assessments.rows[].signals[].factors.{key} |
number | ||
assessments.rows[].signals[].knownContext |
boolean | ||
assessments.rows[].signals[].listsSetAside |
list | ||
assessments.rows[].signals[].listsSetAside[] |
string | ||
assessments.rows[].signals[].score |
number, or null | ||
assessments.rows[].signals[].signal |
string | ||
assessments.rows[].signals[].terms |
object | ||
assessments.rows[].signals[].terms.signIns |
number | ||
assessments.rows[].signals[].terms.userSignIns |
number | ||
assessments.rows[].signals[].terms.users |
number | ||
assessments.rows[].signals[].unknown |
list | ||
assessments.rows[].signals[].unknown[] |
string | ||
assessments.rows[].signals[].what |
string | ||
assessments.rows[].signals[].why |
string | ||
assessments.rows[].subdivision |
string, or null | ||
assessments.rows[].subject |
string, or null | ||
assessments.rows[].uaFamily |
string, or null | ||
assessments.rows[].uaHash |
string, or null | ||
assessments.rows[].uaOs |
string, or null | ||
assessments.rows[].uaPlatform |
string, or null | ||
assessments.rows[].userHref |
string | ||
assessments.rows[].username |
string, or null | ||
assessments.total |
integer | ||
assessmentsInDatabase |
boolean | ||
assessmentsPaging |
object | Which page of how many, and the query parameter that moves it. | |
assessmentsPaging.firstRow |
integer | ||
assessmentsPaging.lastRow |
integer | ||
assessmentsPaging.noun |
string | ||
assessmentsPaging.page |
integer | ||
assessmentsPaging.pages |
integer | ||
assessmentsPaging.param |
string | ||
assessmentsPaging.perPage |
integer | ||
assessmentsPaging.total |
integer | ||
attributions |
list | ||
attributions[].licence |
string, or null | ||
attributions[].licenceUrl |
string, or null | ||
attributions[].modified |
string | ||
attributions[].provider |
string | ||
attributions[].text |
string | ||
attributions[].url |
string, or null | ||
authenticatorLookup |
object | ||
authenticatorLookup.attributions |
list | ||
authenticatorLookup.attributions[].licence |
string, or null | ||
authenticatorLookup.attributions[].licenceUrl |
string, or null | ||
authenticatorLookup.attributions[].modified |
string | ||
authenticatorLookup.attributions[].provider |
string | ||
authenticatorLookup.attributions[].text |
string | ||
authenticatorLookup.attributions[].url |
string, or null | ||
authenticatorLookup.detail |
string | ||
authenticatorLookup.input |
string | ||
authenticatorLookup.key |
string | ||
authenticatorLookup.keyKind |
string | ||
authenticatorLookup.listed |
boolean | ||
authenticatorLookup.model |
object | ||
authenticatorLookup.model.certificationLevel |
string, or null | ||
authenticatorLookup.model.compromised |
boolean | ||
authenticatorLookup.model.description |
string, or null | ||
authenticatorLookup.model.key |
string | ||
authenticatorLookup.model.keyKind |
string | ||
authenticatorLookup.model.latestStatus |
string, or null | ||
authenticatorLookup.model.latestStatusAt |
number | ||
authenticatorLookup.model.metadataStatement |
any JSON | The FIDO Alliance’s MDS3 metadata statement, kept as the BLOB carried it: its shape is the FIDO Metadata Statement specification’s, and which of its optional members a statement has is the vendor’s. The FIDO Alliance’s MDS3 metadata statement, kept as the BLOB carried it: its shape is the FIDO Metadata Statement specification’s, and which of its optional members a statement has is the vendor’s. | |
authenticatorLookup.model.protocolFamily |
string, or null | ||
authenticatorLookup.model.statusReports |
list | ||
authenticatorLookup.model.statusReports[].comment |
string | ||
authenticatorLookup.model.statusReports[].effectiveDate |
string | ||
authenticatorLookup.model.statusReports[].expires |
string | ||
authenticatorLookup.model.statusReports[].reason |
string | ||
authenticatorLookup.model.statusReports[].status |
string | ||
authenticatorLookup.stale |
boolean | ||
authenticatorLookup.version |
string | ||
authenticatorLookup.why |
string | ||
datasets |
list | ||
datasets[].activeVersion |
string | ||
datasets[].attribution |
string, or null | ||
datasets[].attributionUrl |
string, or null | ||
datasets[].dataset |
string | ||
datasets[].formats |
list | ||
datasets[].formats[] |
string | ||
datasets[].kind |
string | ||
datasets[].perRealm |
boolean | ||
datasets[].previousVersion |
string, or null | ||
datasets[].provider |
string, or null | ||
datasets[].publishedAt |
number | ||
datasets[].realm |
string | ||
datasets[].rows |
number | ||
datasets[].staleAfterMs |
number, or null | ||
datasets[].state |
string | ||
datasets[].title |
string | ||
datasets[].versions |
list | ||
datasets[].versions[].activatedAt |
number | ||
datasets[].versions[].attribution |
string, or null | ||
datasets[].versions[].byteCount |
number | ||
datasets[].versions[].dataset |
string | ||
datasets[].versions[].fetchedAt |
number | ||
datasets[].versions[].format |
string | ||
datasets[].versions[].licence |
string, or null | ||
datasets[].versions[].loadedAt |
number | ||
datasets[].versions[].nextUpdateAt |
number | ||
datasets[].versions[].origin |
string, or null | ||
datasets[].versions[].parameters |
map | What was recorded of this version as it loaded. | |
datasets[].versions[].parameters.{key} |
string, or number, or boolean, or null | ||
datasets[].versions[].provider |
string | ||
datasets[].versions[].publishedAt |
number | ||
datasets[].versions[].realm |
string | ||
datasets[].versions[].refusal |
string, or null | ||
datasets[].versions[].reloadable |
boolean | ||
datasets[].versions[].rowCount |
number | ||
datasets[].versions[].rowsDeletedAt |
number | ||
datasets[].versions[].sha256 |
string, or null | ||
datasets[].versions[].source |
string | ||
datasets[].versions[].sourceUri |
string, or null | ||
datasets[].versions[].state |
string | ||
datasets[].versions[].supersededAt |
number | ||
datasets[].versions[].verification |
string, or null | ||
datasets[].versions[].version |
string | ||
datasets[].what |
string | ||
directory |
string | ||
failures |
object | ||
failures.limit |
integer | ||
failures.offset |
integer | ||
failures.rows |
list | ||
failures.rows[].asn |
number | ||
failures.rows[].at |
number | ||
failures.rows[].door |
string | ||
failures.rows[].errorCode |
string, or null | ||
failures.rows[].id |
string, or number | ||
failures.rows[].name |
string | ||
failures.rows[].prefix |
string, or null | ||
failures.rows[].subject |
string, or null | ||
failures.rows[].userHref |
string | ||
failures.rows[].username |
string, or null | ||
failures.store |
object | ||
failures.store.database |
boolean | ||
failures.store.recording |
boolean | ||
failures.store.why |
string | ||
failures.total |
integer | ||
failures.windowDays |
number | ||
failuresPaging |
object | Which page of how many, and the query parameter that moves it. | |
failuresPaging.firstRow |
integer | ||
failuresPaging.lastRow |
integer | ||
failuresPaging.noun |
string | ||
failuresPaging.page |
integer | ||
failuresPaging.pages |
integer | ||
failuresPaging.param |
string | ||
failuresPaging.perPage |
integer | ||
failuresPaging.total |
integer | ||
formats |
list | ||
formats[].format |
string | ||
formats[].provider |
string | ||
formats[].what |
string | ||
lookup |
object | ||
lookup.address |
string | ||
lookup.asn |
object | ||
lookup.asn.accuracyKm |
number | ||
lookup.asn.anonymousProxy |
boolean | ||
lookup.asn.asDomain |
string, or null | ||
lookup.asn.asOrg |
string, or null | ||
lookup.asn.asn |
number | ||
lookup.asn.category |
string, or null | ||
lookup.asn.city |
string, or null | ||
lookup.asn.continent |
string, or null | ||
lookup.asn.country |
string, or null | ||
lookup.asn.dataset |
string | ||
lookup.asn.end |
string | ||
lookup.asn.latitude |
number, or null | ||
lookup.asn.locationId |
number | ||
lookup.asn.longitude |
number, or null | ||
lookup.asn.note |
string, or null | ||
lookup.asn.registeredCountry |
string, or null | ||
lookup.asn.satellite |
boolean | ||
lookup.asn.start |
string | ||
lookup.asn.subdivision |
string, or null | ||
lookup.attributions |
list | ||
lookup.attributions[].licence |
string, or null | ||
lookup.attributions[].licenceUrl |
string, or null | ||
lookup.attributions[].modified |
string | ||
lookup.attributions[].provider |
string | ||
lookup.attributions[].text |
string | ||
lookup.attributions[].url |
string, or null | ||
lookup.datasets |
map | The version of each dataset this was read from. | |
lookup.datasets.{key} |
string | ||
lookup.geo |
object | ||
lookup.geo.accuracyKm |
number | ||
lookup.geo.anonymousProxy |
boolean | ||
lookup.geo.asDomain |
string, or null | ||
lookup.geo.asOrg |
string, or null | ||
lookup.geo.asn |
number | ||
lookup.geo.category |
string, or null | ||
lookup.geo.city |
string, or null | ||
lookup.geo.continent |
string, or null | ||
lookup.geo.country |
string, or null | ||
lookup.geo.dataset |
string | ||
lookup.geo.end |
string | ||
lookup.geo.latitude |
number, or null | ||
lookup.geo.locationId |
number | ||
lookup.geo.longitude |
number, or null | ||
lookup.geo.note |
string, or null | ||
lookup.geo.registeredCountry |
string, or null | ||
lookup.geo.satellite |
boolean | ||
lookup.geo.start |
string | ||
lookup.geo.subdivision |
string, or null | ||
lookup.lists |
list | ||
lookup.lists[].category |
string, or null | ||
lookup.lists[].dataset |
string | ||
lookup.prefix |
string, or null | ||
lookup.stale |
list | ||
lookup.stale[] |
string | ||
providers |
list | ||
providers[].accepted |
object | ||
providers[].accepted.acceptedAt |
number | ||
providers[].accepted.acceptedBy |
string | ||
providers[].accepted.acceptedVia |
string | ||
providers[].accepted.deployment |
string | ||
providers[].accepted.id |
string, or number | ||
providers[].accepted.pageDigest |
string | ||
providers[].accepted.provider |
string | ||
providers[].accepted.termsDigest |
string | ||
providers[].accepted.termsText |
string | ||
providers[].attribution |
string, or null | ||
providers[].changed |
boolean | ||
providers[].licence |
string, or null | ||
providers[].licenceName |
string, or null | ||
providers[].licenceUrl |
string, or null | ||
providers[].needsAcceptance |
boolean | ||
providers[].noAcceptance |
boolean | ||
providers[].provider |
string | ||
providers[].supported |
boolean | ||
providers[].terms |
string, or null | ||
providers[].termsDigest |
string, or null | ||
providers[].termsUrl |
string, or null | ||
providers[].title |
string | ||
providers[].url |
string, or null | ||
realm |
string | ||
realmOnly |
boolean | ||
redistribution |
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 | ||
signals |
list | ||
signals[].factor |
number | ||
signals[].signal |
string | ||
signals[].what |
string | ||
store |
object | ||
store.database |
boolean | ||
store.mode |
string | ||
store.why |
string | ||
subjects |
list | ||
subjects[].actions |
map | Each reaction taken, and the assessment that took it. | |
subjects[].actions.{key} |
string | ||
subjects[].crossedAt |
number | ||
subjects[].feedback |
string, or null | ||
subjects[].lastAssessment |
string, or null | ||
subjects[].level |
string | ||
subjects[].previousLevel |
string, or null | ||
subjects[].reason |
string, or null | ||
subjects[].score |
number, or null | ||
subjects[].subject |
string | ||
subjects[].updatedAt |
number | ||
subjects[].userHref |
string | ||
subjects[].username |
string, or null | ||
subjectsPaging |
object | Which page of how many, and the query parameter that moves it. | |
subjectsPaging.firstRow |
integer | ||
subjectsPaging.lastRow |
integer | ||
subjectsPaging.noun |
string | ||
subjectsPaging.page |
integer | ||
subjectsPaging.pages |
integer | ||
subjectsPaging.param |
string | ||
subjectsPaging.perPage |
integer | ||
subjectsPaging.total |
integer |
POST /admin-api/risk/accept-terms
acceptRiskProviderTerms
Accept a dataset provider’s current terms
Records that the terms of provider, as this build states them (GET /admin-api/risk lists every provider’s terms and digest), are accepted: through the management API, from this deployment, now. No provider’s data is imported without an acceptance of its current terms; a change to the terms needs a new one. The audit row for the request names the caller.
Mirrors POST /admin/risk 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 |
|---|---|---|---|
provider |
one of dbip-lite, ipinfo-lite, tor-project, firehol, operator, fido-mds3, google-android-attestation |
yes |
200: The acceptance recorded.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
POST /admin-api/risk/activate
activateRiskDataset
Make a loaded version of a dataset the active one
The version must have loaded (ready) or have been active before (superseded).
Mirrors POST /admin/risk 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 |
|---|---|---|---|
dataset |
one of geo.city, geo.country, asn, iplist.tor-exit, iplist.reputation, iplist.operator-deny, iplist.operator-allow, fido.mds3, android.attestation-status |
yes | |
realm |
string | ||
version |
string | yes |
200: The active version and the one it replaced.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
POST /admin-api/risk/delete
deleteRiskDatasetVersion
Remove a version: delete its rows
Its record stays, as deleted. A version still loading is refused. Removing the ACTIVE version unloads it (#1152): the dataset has no active version afterwards, nothing else is activated in its place, and rollback is offered when there is an earlier version.
Mirrors POST /admin/risk 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 |
|---|---|---|---|
dataset |
one of geo.city, geo.country, asn, iplist.tor-exit, iplist.reputation, iplist.operator-deny, iplist.operator-allow, fido.mds3, android.attestation-status |
yes | |
realm |
string | ||
version |
string | yes |
200: How many rows were deleted.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
POST /admin-api/risk/import
importRiskDataset
Import one version of a risk dataset, and activate it
Loads content as format into dataset (in realm for an operator list). Refused, and kept as a refused version, when sha256 is named and does not match, when no line is a row, or when it has more than risk.datasetShrinkLimitPercent fewer rows than the active version. A version already recorded is not loaded again (duplicate: true), unless its record is deleted (removed): that one is loaded again (#1155). The provider’s current terms must have been accepted (accept-terms, or acceptTerms: true here) unless the list is the operator’s own. activate: false loads without activating. A file of millions of rows belongs in risk.datasetsDirectory instead.
Mirrors POST /admin/risk 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 |
|---|---|---|---|
acceptTerms |
boolean | Accept the provider’s current terms as part of this import. Without it, an import of a provider whose terms nobody has accepted is refused. | |
activate |
boolean | ||
attribution |
string | ||
content |
string | yes | |
dataset |
one of geo.city, geo.country, asn, iplist.tor-exit, iplist.reputation, iplist.operator-deny, iplist.operator-allow, fido.mds3, android.attestation-status |
yes | |
format |
one of dbip-city-csv, dbip-country-csv, dbip-asn-csv, ipinfo-lite-csv, fido-mds3-jwt, android-attestation-status-json, ip-list |
yes | |
licence |
string | ||
provider |
one of dbip-lite, ipinfo-lite, tor-project, firehol, operator, fido-mds3, google-android-attestation |
||
publishedAt |
string | An ISO 8601 date. | |
realm |
string | ||
sha256 |
string | ||
version |
string |
200: The version, its row count and state.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
GET /admin-api/risk/metrics
getRiskMetrics
The risk scoring system measured
The realm’s assessments over window, counted in the store (database says which): assessments with its total, subjects, bots, meanScore, maxScore, counts byLevel, byDoor, byDecision, byPhase, byCountry, byBand (the score in decades), bySignal, the feedback people gave, and a series of levels per bucketMs; the people at each level now in standings; every signal with its factor and how often it fired; the level thresholds; and, for THIS process since it started, process — assessments made and failed, the time to assess, the reactions taken, observed and failed, the live-session re-checks and the breached-password screening.
Mirrors GET /admin/risk-scoring on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
window |
query | one of 1h, 24h, 7d, 30d |
How far back the assessments are counted; 24h when absent. | |
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 scoring system’s metrics.
| Member | Type | Required | What it is |
|---|---|---|---|
assessments |
object | ||
assessments.bots |
number | ||
assessments.byBand |
map | ||
assessments.byBand.{key} |
number | ||
assessments.byCountry |
map | ||
assessments.byCountry.{key} |
number | ||
assessments.byDecision |
map | ||
assessments.byDecision.{key} |
number | ||
assessments.byDoor |
map | ||
assessments.byDoor.{key} |
number | ||
assessments.byLevel |
map | ||
assessments.byLevel.{key} |
number | ||
assessments.byPhase |
map | ||
assessments.byPhase.{key} |
number | ||
assessments.bySignal |
map | ||
assessments.bySignal.{key} |
number | ||
assessments.bySignalFeedback |
map | ||
assessments.bySignalFeedback.{key} |
map | ||
assessments.bySignalFeedback.{key}.{key} |
number | ||
assessments.bySignalLevel |
map | ||
assessments.bySignalLevel.{key} |
map | ||
assessments.bySignalLevel.{key}.{key} |
number | ||
assessments.feedback |
object | ||
assessments.feedback.confirmed |
number | ||
assessments.feedback.denied |
number | ||
assessments.maxScore |
number | ||
assessments.meanScore |
number | ||
assessments.scoreQuantiles |
map | ||
assessments.scoreQuantiles.{key} |
number | ||
assessments.series |
list | ||
assessments.series[] |
map | ||
assessments.series[].{key} |
number | ||
assessments.subjects |
number | ||
assessments.total |
number | ||
bands |
list | ||
bands[] |
string | ||
bucketMs |
number | ||
calibration |
object | ||
calibration.answered |
number | ||
calibration.assessments |
number | ||
calibration.invalidFactors |
list | ||
calibration.invalidFactors[] |
string | ||
calibration.minimums |
object | ||
calibration.minimums.answersPerSignal |
number | ||
calibration.minimums.assessments |
number | ||
calibration.notMeRate |
number | ||
calibration.signals |
list | ||
calibration.signals[].advice |
string | ||
calibration.signals[].answered |
number | ||
calibration.signals[].builtIn |
number | ||
calibration.signals[].factor |
number | ||
calibration.signals[].fired |
number | ||
calibration.signals[].high |
number | ||
calibration.signals[].notMe |
number | ||
calibration.signals[].signal |
string | ||
calibration.signals[].suggested |
number, or null | ||
calibration.thresholds |
object | ||
calibration.thresholds.high |
object | ||
calibration.thresholds.high.current |
number | ||
calibration.thresholds.high.share |
number | ||
calibration.thresholds.high.suggested |
number, or null | ||
calibration.thresholds.high.target |
number | ||
calibration.thresholds.medium |
object | ||
calibration.thresholds.medium.current |
number | ||
calibration.thresholds.medium.share |
number | ||
calibration.thresholds.medium.suggested |
number, or null | ||
calibration.thresholds.medium.target |
number | ||
database |
boolean | ||
enforced |
boolean | ||
process |
object | ||
process.assessed |
number | ||
process.breachedPasswords |
object | ||
process.breachedPasswords.breached |
number | ||
process.breachedPasswords.enabled |
boolean | ||
process.breachedPasswords.fromCache |
number | ||
process.breachedPasswords.screened |
number | ||
process.breachedPasswords.since |
number | ||
process.breachedPasswords.unanswered |
number | ||
process.durationMs |
object | ||
process.durationMs.max |
number | ||
process.durationMs.mean |
number | ||
process.durationMs.p50 |
number | ||
process.durationMs.p95 |
number | ||
process.durationMs.p99 |
number | ||
process.durationMs.samples |
number | ||
process.failed |
number | ||
process.reactions |
object | ||
process.reactions.failed |
map | ||
process.reactions.failed.{key} |
number | ||
process.reactions.observed |
map | ||
process.reactions.observed.{key} |
number | ||
process.reactions.taken |
map | ||
process.reactions.taken.{key} |
number | ||
process.rescore |
object | ||
process.rescore.raised |
number | ||
process.rescore.runs |
number | ||
process.rescore.sessions |
number | ||
process.since |
number | ||
realm |
string | ||
realmOnly |
boolean | ||
signals |
list | ||
signals[].builtIn |
number | ||
signals[].factor |
number | ||
signals[].fired |
number | ||
signals[].signal |
string | ||
signals[].what |
string | ||
since |
number | ||
standings |
map | ||
standings.{key} |
number | ||
thresholds |
object | ||
thresholds.high |
number | ||
thresholds.medium |
number | ||
window |
string | ||
windowMs |
number | ||
windows |
list | ||
windows[] |
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/risk/reload
reloadRiskDatasetVersion
Download a removed version again, and load it
For a removed (deleted) version of a dataset this service downloads itself (the Android attestation status list, devices.androidStatusUrl; the FIDO MDS3 BLOB, risk.mdsUrl) whose record names the address configured now, as the view’s reloadable says: downloaded again and loaded as that version. Refused when the version is not reloadable (STS-RISK-0051), the download fails (STS-RISK-0052), or the file is not the version’s (STS-RISK-0053: a newer one, which the scheduled download loads). Any other removed version is uploaded again (#1155, #1157).
Mirrors POST /admin/risk 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 |
|---|---|---|---|
dataset |
one of geo.city, geo.country, asn, iplist.tor-exit, iplist.reputation, iplist.operator-deny, iplist.operator-allow, fido.mds3, android.attestation-status |
yes | |
realm |
string | ||
version |
string | yes |
200: What the import answers: the version loaded and active.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
POST /admin-api/risk/rollback
rollbackRiskDataset
Make the previous version of a dataset active again
Refused when there is no previous version.
Mirrors POST /admin/risk 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 |
|---|---|---|---|
dataset |
one of geo.city, geo.country, asn, iplist.tor-exit, iplist.reputation, iplist.operator-deny, iplist.operator-allow, fido.mds3, android.attestation-status |
yes | |
realm |
string |
200: The version now active.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
POST /admin-api/risk/upload
uploadRiskDataset
Upload a risk dataset file, and import it
The request body is the dataset file as its provider publishes it — gzip, a zip holding exactly one file, or plain text, told apart by its first bytes and expanded as it is read, never onto disk — sent as application/octet-stream, application/gzip or application/zip. The fields are query parameters, as POST /admin-api/risk/import takes them in its body; sha256 is of the file as sent. Refused before a byte is read when the declared length is over risk.uploadMaxBytes (413) or the upload directory’s free space cannot hold it (507), and stopped where the body passes the cap. Answers 202 as soon as the file is stored and the version is recorded loading; GET /admin-api/risk then shows it active, or refused with its reason (a decompression bomb past risk.expandedMaxBytes or risk.expansionMaxRatio, a zip of more than one file, a SHA-256 that does not match, no row, a shrink). A refusal found before the version is recorded — the dataset, format, realm or provider, terms not accepted — is the answer (400), as is a version already recorded (200, duplicate: true), unless its record is deleted: a removed version is loaded again (#1155). Send a Content-Length: without one the whole of risk.uploadMaxBytes must be free.
Mirrors POST /admin/risk/upload on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
dataset |
query | one of geo.city, geo.country, asn, iplist.tor-exit, iplist.reputation, iplist.operator-deny, iplist.operator-allow, fido.mds3, android.attestation-status |
yes | The dataset, as GET /admin-api/risk lists them. |
format |
query | one of dbip-city-csv, dbip-country-csv, dbip-asn-csv, ipinfo-lite-csv, fido-mds3-jwt, android-attestation-status-json, ip-list |
yes | The format of the file once expanded. Each dataset takes only some of them, which the handler refuses by name. |
realm |
query | string | The realm, for an operator list only. | |
version |
query | string | The version’s name; its SHA-256 by default. | |
sha256 |
query | string | The SHA-256 of the file AS SENT (compressed, if it is), which the provider publishes; a mismatch refuses the version. | |
publishedAt |
query | string | An ISO 8601 date. | |
provider |
query | one of dbip-lite, ipinfo-lite, tor-project, firehol, operator, fido-mds3, google-android-attestation |
||
licence |
query | string | ||
attribution |
query | string | ||
activate |
query | one of true, false |
false loads without activating. |
|
acceptTerms |
query | one of true, false, on |
Accept the provider’s current terms as part of this import. | |
overrideSignature |
query | one of true, false, on |
fido.mds3 only: load the BLOB even if its signature or signing chain does not verify. Its contents are then UNAUTHENTICATED; the version is recorded with verification: overridden and the reason, and revocation is not checked. Refused for any other dataset. |
|
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/gzip.
As application/octet-stream.
As application/zip.
200: The version already recorded (duplicate: true), or the import’s outcome where it ended before the answer.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
202: Stored and loading: state, dataset, realm, version, sha256, bytes and kind (gzip, zip or plain).
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
400: The operation was refused; errors says why and nothing was handed over.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
413: Larger than risk.uploadMaxBytes.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
415: Not one of the three body types.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |
507: The upload directory has no room for it.
| Member | Type | Required | What it is |
|---|---|---|---|
acceptance |
object | ||
acceptance.acceptedAt |
number | ||
acceptance.acceptedBy |
string | ||
acceptance.acceptedVia |
string | ||
acceptance.deployment |
string | ||
acceptance.id |
string, or number | ||
acceptance.pageDigest |
string | ||
acceptance.provider |
string | ||
acceptance.termsDigest |
string | ||
acceptance.termsText |
string | ||
activated |
boolean | ||
bytes |
number | ||
dataset |
string, or null | ||
duplicate |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
message |
string | ||
ok |
boolean | yes | |
overridden |
string | ||
previous |
string | ||
realm |
string, or null | ||
rows |
number | ||
serial |
number | ||
sha256 |
string | ||
skipped |
number | ||
state |
string | ||
unloaded |
boolean | ||
version |
string, or null |