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/risc
getRisc
The RISC account register: what state each account is in and how many events of which type have been sent about it
Everything /admin/risc and /admin/risc-accounts draw, as JSON. Per account: who it is, the SSF subject a receiver was sent, and THREE states rather than one — the lifecycle (active, disabled, purged), the RISC section 2.8 opt-out state (opt-in, opt-out-initiated, opt-out) and whether a credential has been reported compromised. They move independently: an account can be opted out and perfectly healthy, or compromised and still enabled.
THE REGISTER OUTLIVES THE ACCOUNT, MORE STARKLY THAN THE CAEP ONE OUTLIVES A SESSION. A purged account is gone from the directory entirely, so the row whose lifecycle says purged is the only remaining evidence anywhere that this service ever told anybody it was.
RISC IS A VOCABULARY AND NOT A FAMILY. Its events travel on SSF streams, are signed by the SSF signer and are delivered by the two SSF deliveries, so GET /admin-api/ssf is where the streams themselves are. streams here says only which of them would take a RISC event at all.
suppressed is the one counter with no CAEP equivalent: events this transmitter built and did NOT send, because the account is in the opt-out state and risc.honourOptOut is on. It is the only number here that says a receiver heard nothing ON PURPOSE.
Mirrors GET /admin/risc 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 register, the catalogue and the settings.
| Member | Type | Required | What it is |
|---|---|---|---|
account |
object | ||
account.accountId |
string | ||
account.application |
string | ||
account.counts |
map | ||
account.counts.{key} |
number | ||
account.createdAt |
string, or number, or null | ||
account.credentialChangeRequired |
boolean | ||
account.credentialStanding |
string, or null | ||
account.credentials |
list | ||
account.credentials[].at |
string | ||
account.credentials[].credentialType |
string | ||
account.credentials[].discoveredAt |
number | ||
account.dn |
string, or null | ||
account.email |
string, or null | ||
account.events |
list | ||
account.events[].at |
string | ||
account.events[].jti |
string | ||
account.events[].name |
string | ||
account.events[].streamId |
string | ||
account.events[].uri |
string | ||
account.events[].warnings |
list | ||
account.events[].warnings[] |
string | ||
account.formerIdentifiers |
list | ||
account.formerIdentifiers[] |
string | ||
account.identifierChanges |
list | ||
account.identifierChanges[].at |
string | ||
account.identifierChanges[].from |
string | ||
account.identifierChanges[].to |
string | ||
account.iss |
string, or null | ||
account.kind |
string | ||
account.lifecycle |
string, or null | ||
account.notes |
list | ||
account.notes[] |
string | ||
account.optOut |
string, or null | ||
account.optOutApplies |
boolean | ||
account.phone |
string, or null | ||
account.realm |
string, or null | ||
account.recoveryActivated |
boolean | ||
account.serviceAccount |
boolean | ||
account.streams |
list | ||
account.streams[] |
string | ||
account.sub |
string, or null | ||
account.subject |
string | ||
account.suppressed |
integer | ||
account.total |
integer | ||
account.updatedAt |
string, or number, or null | ||
account.username |
string, or null | ||
accounts |
list | ||
accounts[].accountId |
string | ||
accounts[].application |
string | ||
accounts[].counts |
map | ||
accounts[].counts.{key} |
number | ||
accounts[].createdAt |
string, or number, or null | ||
accounts[].credentialChangeRequired |
boolean | ||
accounts[].credentialStanding |
string, or null | ||
accounts[].credentials |
list | ||
accounts[].credentials[].at |
string | ||
accounts[].credentials[].credentialType |
string | ||
accounts[].credentials[].discoveredAt |
number | ||
accounts[].dn |
string, or null | ||
accounts[].email |
string, or null | ||
accounts[].events |
list | ||
accounts[].events[].at |
string | ||
accounts[].events[].jti |
string | ||
accounts[].events[].name |
string | ||
accounts[].events[].streamId |
string | ||
accounts[].events[].uri |
string | ||
accounts[].events[].warnings |
list | ||
accounts[].events[].warnings[] |
string | ||
accounts[].formerIdentifiers |
list | ||
accounts[].formerIdentifiers[] |
string | ||
accounts[].identifierChanges |
list | ||
accounts[].identifierChanges[].at |
string | ||
accounts[].identifierChanges[].from |
string | ||
accounts[].identifierChanges[].to |
string | ||
accounts[].iss |
string, or null | ||
accounts[].kind |
string | ||
accounts[].lifecycle |
string, or null | ||
accounts[].notes |
list | ||
accounts[].notes[] |
string | ||
accounts[].optOut |
string, or null | ||
accounts[].optOutApplies |
boolean | ||
accounts[].phone |
string, or null | ||
accounts[].realm |
string, or null | ||
accounts[].recoveryActivated |
boolean | ||
accounts[].serviceAccount |
boolean | ||
accounts[].streams |
list | ||
accounts[].streams[] |
string | ||
accounts[].sub |
string, or null | ||
accounts[].subject |
string | ||
accounts[].suppressed |
integer | ||
accounts[].total |
integer | ||
accounts[].updatedAt |
string, or number, or null | ||
accounts[].username |
string, or null | ||
applications |
list | ||
applications[].accounts |
integer | ||
applications[].acknowledged |
integer | ||
applications[].audiences |
list | ||
applications[].audiences[] |
string | ||
applications[].counts |
map | ||
applications[].counts.{key} |
number | ||
applications[].declared |
boolean | ||
applications[].delivered |
integer | ||
applications[].deliveries |
list | ||
applications[].deliveries[] |
string | ||
applications[].dn |
string | ||
applications[].enabled |
integer | ||
applications[].endpoints |
list | ||
applications[].endpoints[] |
string | ||
applications[].failed |
integer | ||
applications[].identifier |
string | ||
applications[].lastPushAt |
string, or number, or null | ||
applications[].lastPushError |
string, or null | ||
applications[].name |
string, or null | ||
applications[].queued |
integer | ||
applications[].receiverErrors |
integer | ||
applications[].registered |
boolean | ||
applications[].sessions |
integer | ||
applications[].streamCount |
integer | ||
applications[].streams |
list | ||
applications[].streams[] |
string | ||
applications[].takes |
list | ||
applications[].takes[] |
string | ||
applications[].total |
integer | ||
autoEmit |
boolean | ||
autoEmitActs |
list | ||
autoEmitActs[] |
string | ||
cap |
number | ||
catalogue |
list | ||
catalogue[].deprecated |
string | ||
catalogue[].family |
string | ||
catalogue[].members |
list | ||
catalogue[].members[].name |
string | ||
catalogue[].members[].required |
boolean, or string, or null | ||
catalogue[].members[].type |
string, or null | ||
catalogue[].members[].values |
list | ||
catalogue[].members[].values[] |
string | ||
catalogue[].members[].what |
string | ||
catalogue[].name |
string | ||
catalogue[].offered |
boolean | ||
catalogue[].required |
list | ||
catalogue[].required[] |
string | ||
catalogue[].short |
string | ||
catalogue[].subject |
boolean, or string, or null | ||
catalogue[].subjectFormats |
list | ||
catalogue[].subjectFormats[] |
string | ||
catalogue[].uri |
string | ||
catalogue[].what |
string | ||
enabled |
boolean | ||
eventTypes |
list | ||
eventTypes[].deprecated |
string | ||
eventTypes[].family |
string | ||
eventTypes[].members |
list | ||
eventTypes[].members[].name |
string | ||
eventTypes[].members[].required |
boolean, or string, or null | ||
eventTypes[].members[].type |
string, or null | ||
eventTypes[].members[].values |
list | ||
eventTypes[].members[].values[] |
string | ||
eventTypes[].members[].what |
string | ||
eventTypes[].name |
string | ||
eventTypes[].offered |
boolean | ||
eventTypes[].required |
list | ||
eventTypes[].required[] |
string | ||
eventTypes[].short |
string | ||
eventTypes[].subject |
boolean, or string, or null | ||
eventTypes[].subjectFormats |
list | ||
eventTypes[].subjectFormats[] |
string | ||
eventTypes[].uri |
string | ||
eventTypes[].what |
string | ||
events |
list | ||
events[].at |
string | ||
events[].jti |
string | ||
events[].name |
string | ||
events[].streamId |
string | ||
events[].uri |
string | ||
events[].warnings |
list | ||
events[].warnings[] |
string | ||
filter |
object | ||
filter.accounts |
string, or null | ||
filter.applications |
string, or null | ||
googleSubjectType |
boolean | ||
honourOptOut |
boolean | ||
id |
string | ||
installed |
boolean | ||
issuer |
string | ||
lifecycleStates |
list | ||
lifecycleStates[] |
string | ||
matched |
object | ||
matched.accounts |
integer | ||
matched.applications |
integer | ||
matched.streams |
integer | ||
note |
string | ||
omitEventTimestamp |
boolean | ||
optStates |
list | ||
optStates[] |
string | ||
paging |
object | ||
paging.accounts |
object | ||
paging.accounts.firstRow |
integer | ||
paging.accounts.lastRow |
integer | ||
paging.accounts.noun |
string | ||
paging.accounts.page |
integer | ||
paging.accounts.pages |
integer | ||
paging.accounts.param |
string | ||
paging.accounts.perPage |
integer | ||
paging.accounts.total |
integer | ||
paging.applications |
object | ||
paging.applications.firstRow |
integer | ||
paging.applications.lastRow |
integer | ||
paging.applications.noun |
string | ||
paging.applications.page |
integer | ||
paging.applications.pages |
integer | ||
paging.applications.param |
string | ||
paging.applications.perPage |
integer | ||
paging.applications.total |
integer | ||
paging.events |
object | ||
paging.events.firstRow |
integer | ||
paging.events.lastRow |
integer | ||
paging.events.noun |
string | ||
paging.events.page |
integer | ||
paging.events.pages |
integer | ||
paging.events.param |
string | ||
paging.events.perPage |
integer | ||
paging.events.total |
integer | ||
paging.streams |
object | ||
paging.streams.firstRow |
integer | ||
paging.streams.lastRow |
integer | ||
paging.streams.noun |
string | ||
paging.streams.page |
integer | ||
paging.streams.pages |
integer | ||
paging.streams.param |
string | ||
paging.streams.perPage |
integer | ||
paging.streams.total |
integer | ||
settings |
object | ||
settings.context |
object | ||
settings.context.configFile |
string, or null | ||
settings.context.defaultsFile |
string, or null | ||
settings.context.inRealm |
boolean | ||
settings.context.persistenceMode |
string | ||
settings.context.persistsAppconfig |
boolean | ||
settings.context.persistsRealms |
boolean | ||
settings.context.realmId |
string | ||
settings.editableCount |
integer | ||
settings.groups |
list | ||
settings.groups[].group |
string | ||
settings.groups[].settings |
list | ||
settings.groups[].settings[].appconfigPath |
string | ||
settings.groups[].settings[].csvValueNotes |
map | ||
settings.groups[].settings[].csvValueNotes.{key} |
string | ||
settings.groups[].settings[].csvValues |
list | ||
settings.groups[].settings[].csvValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].default |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].default[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].description |
string | ||
settings.groups[].settings[].editRefusal |
string | ||
settings.groups[].settings[].editable |
boolean | ||
settings.groups[].settings[].enumValues |
list | ||
settings.groups[].settings[].enumValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].env |
list, or string | ||
settings.groups[].settings[].env[] |
string | ||
settings.groups[].settings[].group |
string | ||
settings.groups[].settings[].key |
string | ||
settings.groups[].settings[].label |
string | ||
settings.groups[].settings[].legacyEnv |
list, or string | ||
settings.groups[].settings[].legacyEnv[] |
string | ||
settings.groups[].settings[].masked |
boolean | ||
settings.groups[].settings[].max |
number | ||
settings.groups[].settings[].min |
number | ||
settings.groups[].settings[].ordered |
boolean | ||
settings.groups[].settings[].overridden |
boolean | ||
settings.groups[].settings[].realmSettable |
boolean | ||
settings.groups[].settings[].restartReason |
string | ||
settings.groups[].settings[].selectAll |
object | ||
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 |
string | ||
settings.groups[].settings[].step |
number | ||
settings.groups[].settings[].text |
string, or null | ||
settings.groups[].settings[].type |
string | ||
settings.groups[].settings[].value |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].value[] |
string, or number, or boolean, or null | ||
settings.overridden |
list | ||
settings.overridden[] |
string | ||
settings.page |
string | ||
settings.setWith |
string | ||
settings.settingCount |
integer | ||
settings.sharedWith |
map | ||
settings.sharedWith.{key} |
list | ||
settings.sharedWith.{key}[].label |
string | ||
settings.sharedWith.{key}[].path |
string | ||
shown |
object | ||
shown.accounts |
list | ||
shown.accounts[].accountId |
string | ||
shown.accounts[].application |
string | ||
shown.accounts[].counts |
map | ||
shown.accounts[].counts.{key} |
number | ||
shown.accounts[].createdAt |
string, or number, or null | ||
shown.accounts[].credentialChangeRequired |
boolean | ||
shown.accounts[].credentialStanding |
string, or null | ||
shown.accounts[].credentials |
list | ||
shown.accounts[].credentials[].at |
string | ||
shown.accounts[].credentials[].credentialType |
string | ||
shown.accounts[].credentials[].discoveredAt |
number | ||
shown.accounts[].dn |
string, or null | ||
shown.accounts[].email |
string, or null | ||
shown.accounts[].events |
list | ||
shown.accounts[].events[].at |
string | ||
shown.accounts[].events[].jti |
string | ||
shown.accounts[].events[].name |
string | ||
shown.accounts[].events[].streamId |
string | ||
shown.accounts[].events[].uri |
string | ||
shown.accounts[].events[].warnings |
list | ||
shown.accounts[].events[].warnings[] |
string | ||
shown.accounts[].formerIdentifiers |
list | ||
shown.accounts[].formerIdentifiers[] |
string | ||
shown.accounts[].identifierChanges |
list | ||
shown.accounts[].identifierChanges[].at |
string | ||
shown.accounts[].identifierChanges[].from |
string | ||
shown.accounts[].identifierChanges[].to |
string | ||
shown.accounts[].iss |
string, or null | ||
shown.accounts[].kind |
string | ||
shown.accounts[].lifecycle |
string, or null | ||
shown.accounts[].notes |
list | ||
shown.accounts[].notes[] |
string | ||
shown.accounts[].optOut |
string, or null | ||
shown.accounts[].optOutApplies |
boolean | ||
shown.accounts[].phone |
string, or null | ||
shown.accounts[].realm |
string, or null | ||
shown.accounts[].recoveryActivated |
boolean | ||
shown.accounts[].serviceAccount |
boolean | ||
shown.accounts[].streams |
list | ||
shown.accounts[].streams[] |
string | ||
shown.accounts[].sub |
string, or null | ||
shown.accounts[].subject |
string | ||
shown.accounts[].suppressed |
integer | ||
shown.accounts[].total |
integer | ||
shown.accounts[].updatedAt |
string, or number, or null | ||
shown.accounts[].username |
string, or null | ||
shown.applications |
list | ||
shown.applications[].accounts |
integer | ||
shown.applications[].acknowledged |
integer | ||
shown.applications[].audiences |
list | ||
shown.applications[].audiences[] |
string | ||
shown.applications[].counts |
map | ||
shown.applications[].counts.{key} |
number | ||
shown.applications[].declared |
boolean | ||
shown.applications[].delivered |
integer | ||
shown.applications[].deliveries |
list | ||
shown.applications[].deliveries[] |
string | ||
shown.applications[].dn |
string | ||
shown.applications[].enabled |
integer | ||
shown.applications[].endpoints |
list | ||
shown.applications[].endpoints[] |
string | ||
shown.applications[].failed |
integer | ||
shown.applications[].identifier |
string | ||
shown.applications[].lastPushAt |
string, or number, or null | ||
shown.applications[].lastPushError |
string, or null | ||
shown.applications[].name |
string, or null | ||
shown.applications[].queued |
integer | ||
shown.applications[].receiverErrors |
integer | ||
shown.applications[].registered |
boolean | ||
shown.applications[].sessions |
integer | ||
shown.applications[].streamCount |
integer | ||
shown.applications[].streams |
list | ||
shown.applications[].streams[] |
string | ||
shown.applications[].takes |
list | ||
shown.applications[].takes[] |
string | ||
shown.applications[].total |
integer | ||
shown.streams |
list | ||
shown.streams[].aud |
list, or string, or null | ||
shown.streams[].aud[] |
string | ||
shown.streams[].delivery |
string | ||
shown.streams[].status |
string | ||
shown.streams[].stream_id |
string | ||
shown.streams[].subjects |
integer | ||
shown.streams[].takes |
list | ||
shown.streams[].takes[] |
string | ||
ssfEnabled |
boolean | ||
streamCounts |
object | ||
streamCounts.taking |
integer | ||
streamCounts.total |
integer | ||
streams |
list | ||
streams[].aud |
list, or string, or null | ||
streams[].aud[] |
string | ||
streams[].delivery |
string | ||
streams[].status |
string | ||
streams[].stream_id |
string | ||
streams[].subjects |
integer | ||
streams[].takes |
list | ||
streams[].takes[] |
string | ||
subjectFormat |
string | ||
totals |
map | ||
totals.{key} |
number | ||
tracked |
integer |
GET /admin-api/risc/accounts
getRiscAccounts
The RISC account register, searched and paged — or one account with everything that has been said about it
What /admin/risc-accounts draws. Without account it is the register: one row per account this service has been told anything about, including ones that no longer exist, searched with acctq and paged with accountsPage and per. Beside it, applications: what this transmitter has said to each RECEIVER across every account, searched with rappq.
With account it is that one account opened out: the events actually sent about it, in order, with the jti and the stream each went out on and what the register noticed as it was applied, paged with eventsPage.
THE SEARCH REACHES IDENTIFIERS THE ACCOUNT NO LONGER HAS, and that is not thoroughness: identifier-changed is an event ABOUT the key, so the address a caller is holding — out of a log, off an event it is chasing — is routinely the superseded one. A search that matched only the current spelling would hide exactly the row somebody came to find.
An account that names nothing answers 200 with account: null rather than 404: this register is capped at risc.maxAccountsTracked and drops the oldest.
Mirrors GET /admin/risc-accounts on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
acctq |
query | string | Narrows the register to rows whose account id, username, sub, email address, telephone number, SSF subject, directory DN or any FORMER identifier contains this. |
|
account |
query | string | One account id. The reply is then that account and its events rather than the list. | |
accountsPage |
query | integer | Which page of the register. Clamped, like every page parameter here. | |
rappq |
query | string | Narrows the per-receiver list to rows whose application name, identifier or stream aud contains this. It deliberately does NOT match event types: a receiver that takes none of the fourteen is exactly the row somebody is looking for when they ask why nothing arrived. |
|
rapplicationsPage |
query | integer | Which page of the per-receiver list. It shares per with the register above it. |
|
streamsPage |
query | integer | Which page of the streams a RISC event could go to. It shares per with the two lists above. |
|
eventsPage |
query | integer | Which page of ONE account’s events, with account. |
|
page |
query | integer | Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is. | |
per |
query | integer | Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own. | |
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
200: The register, or one account and its events.
| Member | Type | Required | What it is |
|---|---|---|---|
account |
object | ||
account.accountId |
string | ||
account.application |
string | ||
account.counts |
map | ||
account.counts.{key} |
number | ||
account.createdAt |
string, or number, or null | ||
account.credentialChangeRequired |
boolean | ||
account.credentialStanding |
string, or null | ||
account.credentials |
list | ||
account.credentials[].at |
string | ||
account.credentials[].credentialType |
string | ||
account.credentials[].discoveredAt |
number | ||
account.dn |
string, or null | ||
account.email |
string, or null | ||
account.events |
list | ||
account.events[].at |
string | ||
account.events[].jti |
string | ||
account.events[].name |
string | ||
account.events[].streamId |
string | ||
account.events[].uri |
string | ||
account.events[].warnings |
list | ||
account.events[].warnings[] |
string | ||
account.formerIdentifiers |
list | ||
account.formerIdentifiers[] |
string | ||
account.identifierChanges |
list | ||
account.identifierChanges[].at |
string | ||
account.identifierChanges[].from |
string | ||
account.identifierChanges[].to |
string | ||
account.iss |
string, or null | ||
account.kind |
string | ||
account.lifecycle |
string, or null | ||
account.notes |
list | ||
account.notes[] |
string | ||
account.optOut |
string, or null | ||
account.optOutApplies |
boolean | ||
account.phone |
string, or null | ||
account.realm |
string, or null | ||
account.recoveryActivated |
boolean | ||
account.serviceAccount |
boolean | ||
account.streams |
list | ||
account.streams[] |
string | ||
account.sub |
string, or null | ||
account.subject |
string | ||
account.suppressed |
integer | ||
account.total |
integer | ||
account.updatedAt |
string, or number, or null | ||
account.username |
string, or null | ||
accounts |
list | ||
accounts[].accountId |
string | ||
accounts[].application |
string | ||
accounts[].counts |
map | ||
accounts[].counts.{key} |
number | ||
accounts[].createdAt |
string, or number, or null | ||
accounts[].credentialChangeRequired |
boolean | ||
accounts[].credentialStanding |
string, or null | ||
accounts[].credentials |
list | ||
accounts[].credentials[].at |
string | ||
accounts[].credentials[].credentialType |
string | ||
accounts[].credentials[].discoveredAt |
number | ||
accounts[].dn |
string, or null | ||
accounts[].email |
string, or null | ||
accounts[].events |
list | ||
accounts[].events[].at |
string | ||
accounts[].events[].jti |
string | ||
accounts[].events[].name |
string | ||
accounts[].events[].streamId |
string | ||
accounts[].events[].uri |
string | ||
accounts[].events[].warnings |
list | ||
accounts[].events[].warnings[] |
string | ||
accounts[].formerIdentifiers |
list | ||
accounts[].formerIdentifiers[] |
string | ||
accounts[].identifierChanges |
list | ||
accounts[].identifierChanges[].at |
string | ||
accounts[].identifierChanges[].from |
string | ||
accounts[].identifierChanges[].to |
string | ||
accounts[].iss |
string, or null | ||
accounts[].kind |
string | ||
accounts[].lifecycle |
string, or null | ||
accounts[].notes |
list | ||
accounts[].notes[] |
string | ||
accounts[].optOut |
string, or null | ||
accounts[].optOutApplies |
boolean | ||
accounts[].phone |
string, or null | ||
accounts[].realm |
string, or null | ||
accounts[].recoveryActivated |
boolean | ||
accounts[].serviceAccount |
boolean | ||
accounts[].streams |
list | ||
accounts[].streams[] |
string | ||
accounts[].sub |
string, or null | ||
accounts[].subject |
string | ||
accounts[].suppressed |
integer | ||
accounts[].total |
integer | ||
accounts[].updatedAt |
string, or number, or null | ||
accounts[].username |
string, or null | ||
applications |
list | ||
applications[].accounts |
integer | ||
applications[].acknowledged |
integer | ||
applications[].audiences |
list | ||
applications[].audiences[] |
string | ||
applications[].counts |
map | ||
applications[].counts.{key} |
number | ||
applications[].declared |
boolean | ||
applications[].delivered |
integer | ||
applications[].deliveries |
list | ||
applications[].deliveries[] |
string | ||
applications[].dn |
string | ||
applications[].enabled |
integer | ||
applications[].endpoints |
list | ||
applications[].endpoints[] |
string | ||
applications[].failed |
integer | ||
applications[].identifier |
string | ||
applications[].lastPushAt |
string, or number, or null | ||
applications[].lastPushError |
string, or null | ||
applications[].name |
string, or null | ||
applications[].queued |
integer | ||
applications[].receiverErrors |
integer | ||
applications[].registered |
boolean | ||
applications[].sessions |
integer | ||
applications[].streamCount |
integer | ||
applications[].streams |
list | ||
applications[].streams[] |
string | ||
applications[].takes |
list | ||
applications[].takes[] |
string | ||
applications[].total |
integer | ||
autoEmit |
boolean | ||
autoEmitActs |
list | ||
autoEmitActs[] |
string | ||
cap |
number | ||
catalogue |
list | ||
catalogue[].deprecated |
string | ||
catalogue[].family |
string | ||
catalogue[].members |
list | ||
catalogue[].members[].name |
string | ||
catalogue[].members[].required |
boolean, or string, or null | ||
catalogue[].members[].type |
string, or null | ||
catalogue[].members[].values |
list | ||
catalogue[].members[].values[] |
string | ||
catalogue[].members[].what |
string | ||
catalogue[].name |
string | ||
catalogue[].offered |
boolean | ||
catalogue[].required |
list | ||
catalogue[].required[] |
string | ||
catalogue[].short |
string | ||
catalogue[].subject |
boolean, or string, or null | ||
catalogue[].subjectFormats |
list | ||
catalogue[].subjectFormats[] |
string | ||
catalogue[].uri |
string | ||
catalogue[].what |
string | ||
enabled |
boolean | ||
eventTypes |
list | ||
eventTypes[].deprecated |
string | ||
eventTypes[].family |
string | ||
eventTypes[].members |
list | ||
eventTypes[].members[].name |
string | ||
eventTypes[].members[].required |
boolean, or string, or null | ||
eventTypes[].members[].type |
string, or null | ||
eventTypes[].members[].values |
list | ||
eventTypes[].members[].values[] |
string | ||
eventTypes[].members[].what |
string | ||
eventTypes[].name |
string | ||
eventTypes[].offered |
boolean | ||
eventTypes[].required |
list | ||
eventTypes[].required[] |
string | ||
eventTypes[].short |
string | ||
eventTypes[].subject |
boolean, or string, or null | ||
eventTypes[].subjectFormats |
list | ||
eventTypes[].subjectFormats[] |
string | ||
eventTypes[].uri |
string | ||
eventTypes[].what |
string | ||
events |
list | ||
events[].at |
string | ||
events[].jti |
string | ||
events[].name |
string | ||
events[].streamId |
string | ||
events[].uri |
string | ||
events[].warnings |
list | ||
events[].warnings[] |
string | ||
filter |
object | ||
filter.accounts |
string, or null | ||
filter.applications |
string, or null | ||
googleSubjectType |
boolean | ||
honourOptOut |
boolean | ||
id |
string | ||
installed |
boolean | ||
issuer |
string | ||
lifecycleStates |
list | ||
lifecycleStates[] |
string | ||
matched |
object | ||
matched.accounts |
integer | ||
matched.applications |
integer | ||
matched.streams |
integer | ||
note |
string | ||
omitEventTimestamp |
boolean | ||
optStates |
list | ||
optStates[] |
string | ||
paging |
object | ||
paging.accounts |
object | ||
paging.accounts.firstRow |
integer | ||
paging.accounts.lastRow |
integer | ||
paging.accounts.noun |
string | ||
paging.accounts.page |
integer | ||
paging.accounts.pages |
integer | ||
paging.accounts.param |
string | ||
paging.accounts.perPage |
integer | ||
paging.accounts.total |
integer | ||
paging.applications |
object | ||
paging.applications.firstRow |
integer | ||
paging.applications.lastRow |
integer | ||
paging.applications.noun |
string | ||
paging.applications.page |
integer | ||
paging.applications.pages |
integer | ||
paging.applications.param |
string | ||
paging.applications.perPage |
integer | ||
paging.applications.total |
integer | ||
paging.events |
object | ||
paging.events.firstRow |
integer | ||
paging.events.lastRow |
integer | ||
paging.events.noun |
string | ||
paging.events.page |
integer | ||
paging.events.pages |
integer | ||
paging.events.param |
string | ||
paging.events.perPage |
integer | ||
paging.events.total |
integer | ||
paging.streams |
object | ||
paging.streams.firstRow |
integer | ||
paging.streams.lastRow |
integer | ||
paging.streams.noun |
string | ||
paging.streams.page |
integer | ||
paging.streams.pages |
integer | ||
paging.streams.param |
string | ||
paging.streams.perPage |
integer | ||
paging.streams.total |
integer | ||
settings |
object | ||
settings.context |
object | ||
settings.context.configFile |
string, or null | ||
settings.context.defaultsFile |
string, or null | ||
settings.context.inRealm |
boolean | ||
settings.context.persistenceMode |
string | ||
settings.context.persistsAppconfig |
boolean | ||
settings.context.persistsRealms |
boolean | ||
settings.context.realmId |
string | ||
settings.editableCount |
integer | ||
settings.groups |
list | ||
settings.groups[].group |
string | ||
settings.groups[].settings |
list | ||
settings.groups[].settings[].appconfigPath |
string | ||
settings.groups[].settings[].csvValueNotes |
map | ||
settings.groups[].settings[].csvValueNotes.{key} |
string | ||
settings.groups[].settings[].csvValues |
list | ||
settings.groups[].settings[].csvValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].default |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].default[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].description |
string | ||
settings.groups[].settings[].editRefusal |
string | ||
settings.groups[].settings[].editable |
boolean | ||
settings.groups[].settings[].enumValues |
list | ||
settings.groups[].settings[].enumValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].env |
list, or string | ||
settings.groups[].settings[].env[] |
string | ||
settings.groups[].settings[].group |
string | ||
settings.groups[].settings[].key |
string | ||
settings.groups[].settings[].label |
string | ||
settings.groups[].settings[].legacyEnv |
list, or string | ||
settings.groups[].settings[].legacyEnv[] |
string | ||
settings.groups[].settings[].masked |
boolean | ||
settings.groups[].settings[].max |
number | ||
settings.groups[].settings[].min |
number | ||
settings.groups[].settings[].ordered |
boolean | ||
settings.groups[].settings[].overridden |
boolean | ||
settings.groups[].settings[].realmSettable |
boolean | ||
settings.groups[].settings[].restartReason |
string | ||
settings.groups[].settings[].selectAll |
object | ||
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 |
string | ||
settings.groups[].settings[].step |
number | ||
settings.groups[].settings[].text |
string, or null | ||
settings.groups[].settings[].type |
string | ||
settings.groups[].settings[].value |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].value[] |
string, or number, or boolean, or null | ||
settings.overridden |
list | ||
settings.overridden[] |
string | ||
settings.page |
string | ||
settings.setWith |
string | ||
settings.settingCount |
integer | ||
settings.sharedWith |
map | ||
settings.sharedWith.{key} |
list | ||
settings.sharedWith.{key}[].label |
string | ||
settings.sharedWith.{key}[].path |
string | ||
shown |
object | ||
shown.accounts |
list | ||
shown.accounts[].accountId |
string | ||
shown.accounts[].application |
string | ||
shown.accounts[].counts |
map | ||
shown.accounts[].counts.{key} |
number | ||
shown.accounts[].createdAt |
string, or number, or null | ||
shown.accounts[].credentialChangeRequired |
boolean | ||
shown.accounts[].credentialStanding |
string, or null | ||
shown.accounts[].credentials |
list | ||
shown.accounts[].credentials[].at |
string | ||
shown.accounts[].credentials[].credentialType |
string | ||
shown.accounts[].credentials[].discoveredAt |
number | ||
shown.accounts[].dn |
string, or null | ||
shown.accounts[].email |
string, or null | ||
shown.accounts[].events |
list | ||
shown.accounts[].events[].at |
string | ||
shown.accounts[].events[].jti |
string | ||
shown.accounts[].events[].name |
string | ||
shown.accounts[].events[].streamId |
string | ||
shown.accounts[].events[].uri |
string | ||
shown.accounts[].events[].warnings |
list | ||
shown.accounts[].events[].warnings[] |
string | ||
shown.accounts[].formerIdentifiers |
list | ||
shown.accounts[].formerIdentifiers[] |
string | ||
shown.accounts[].identifierChanges |
list | ||
shown.accounts[].identifierChanges[].at |
string | ||
shown.accounts[].identifierChanges[].from |
string | ||
shown.accounts[].identifierChanges[].to |
string | ||
shown.accounts[].iss |
string, or null | ||
shown.accounts[].kind |
string | ||
shown.accounts[].lifecycle |
string, or null | ||
shown.accounts[].notes |
list | ||
shown.accounts[].notes[] |
string | ||
shown.accounts[].optOut |
string, or null | ||
shown.accounts[].optOutApplies |
boolean | ||
shown.accounts[].phone |
string, or null | ||
shown.accounts[].realm |
string, or null | ||
shown.accounts[].recoveryActivated |
boolean | ||
shown.accounts[].serviceAccount |
boolean | ||
shown.accounts[].streams |
list | ||
shown.accounts[].streams[] |
string | ||
shown.accounts[].sub |
string, or null | ||
shown.accounts[].subject |
string | ||
shown.accounts[].suppressed |
integer | ||
shown.accounts[].total |
integer | ||
shown.accounts[].updatedAt |
string, or number, or null | ||
shown.accounts[].username |
string, or null | ||
shown.applications |
list | ||
shown.applications[].accounts |
integer | ||
shown.applications[].acknowledged |
integer | ||
shown.applications[].audiences |
list | ||
shown.applications[].audiences[] |
string | ||
shown.applications[].counts |
map | ||
shown.applications[].counts.{key} |
number | ||
shown.applications[].declared |
boolean | ||
shown.applications[].delivered |
integer | ||
shown.applications[].deliveries |
list | ||
shown.applications[].deliveries[] |
string | ||
shown.applications[].dn |
string | ||
shown.applications[].enabled |
integer | ||
shown.applications[].endpoints |
list | ||
shown.applications[].endpoints[] |
string | ||
shown.applications[].failed |
integer | ||
shown.applications[].identifier |
string | ||
shown.applications[].lastPushAt |
string, or number, or null | ||
shown.applications[].lastPushError |
string, or null | ||
shown.applications[].name |
string, or null | ||
shown.applications[].queued |
integer | ||
shown.applications[].receiverErrors |
integer | ||
shown.applications[].registered |
boolean | ||
shown.applications[].sessions |
integer | ||
shown.applications[].streamCount |
integer | ||
shown.applications[].streams |
list | ||
shown.applications[].streams[] |
string | ||
shown.applications[].takes |
list | ||
shown.applications[].takes[] |
string | ||
shown.applications[].total |
integer | ||
shown.streams |
list | ||
shown.streams[].aud |
list, or string, or null | ||
shown.streams[].aud[] |
string | ||
shown.streams[].delivery |
string | ||
shown.streams[].status |
string | ||
shown.streams[].stream_id |
string | ||
shown.streams[].subjects |
integer | ||
shown.streams[].takes |
list | ||
shown.streams[].takes[] |
string | ||
ssfEnabled |
boolean | ||
streamCounts |
object | ||
streamCounts.taking |
integer | ||
streamCounts.total |
integer | ||
streams |
list | ||
streams[].aud |
list, or string, or null | ||
streams[].aud[] |
string | ||
streams[].delivery |
string | ||
streams[].status |
string | ||
streams[].stream_id |
string | ||
streams[].subjects |
integer | ||
streams[].takes |
list | ||
streams[].takes[] |
string | ||
subjectFormat |
string | ||
totals |
map | ||
totals.{key} |
number | ||
tracked |
integer |
POST /admin-api/risc/clear
clearRiscAccounts
Drop every row in the RISC account register
Forgets what has been said about every account. Nobody is disabled, nobody is deleted and no directory entry is touched. A row whose holder chose anything but opt-in is re-created blank with that choice kept (RISC section 2.8).
It is worth knowing what this throws away: a row for an account that has been PURGED is the only evidence anywhere in this service that the account existed and that receivers were told it was deleted. The directory cannot supply it, because the entry is gone.
Mirrors POST /admin/risc 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: How many rows were dropped.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/risc/emit
emitRiscEvent
Send one RISC event about one account
Builds the payload, composes the SUBJECT from the account in the format risc.subjectFormat names, and transmits it on every stream that both delivers the type and covers that subject.
ELEVEN OF THE FOURTEEN CARRY NO PAYLOAD MEMBERS AT ALL, so for those the subject is the entire message and payload is left empty. Only credential-compromise has a REQUIRED member, credential_type, which RISC defines by reference to CAEP’s credential-change — the two lists are the same list.
EVERY ONE OF THE FOURTEEN HAS SOMETHING HERE THAT SENDS IT when it happens (docs/shared-signals.md lists each, #164), where risc.autoEmit is on and risc.autoEmitTypes names it, which by default is all but the deprecated sessions-revoked. This sends any of them by hand, whatever that is.
FOUR OF THEM CHANGE REAL STATE WHEN THEY GO. RISC section 2.8 defines each opt-out event as “the account is in this state” rather than as a report that it moved, so emitting opt-out-effective here IS the transition — and the next event about that account is suppressed while risc.honourOptOut is on.
AN ACCOUNT THIS SERVICE HAS NEVER HELD IS ACCEPTED, which is the opposite of what emitCaepEvent does with an unknown session. A session identifier this service never minted is one it can compose no subject from; an account is a person, and RISC is aimed ACROSS providers, so the account a receiver is warned about is usually one it has never seen.
A TYPE NO STREAM TAKES IS NOT AN ERROR. The account’s state is still updated and the reply says nothing was sent.
Mirrors POST /admin/risc 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 |
|---|---|---|---|
account_id |
string | yes | The account it is about, from GET /admin-api/risc. A name no row carries is accepted and opens one. |
payload |
string | The event-specific members, as JSON. Empty for a conforming specimen of the type, which is what eleven of the fourteen always are. Note the HYPHEN in identifier-changed’s new-value: it is the only hyphenated member name in any of the three vocabularies, and new_value is carried and silently ignored by a receiver. |
|
reason_admin |
string | Why, for a log. Sent as an object keyed by risc.reasonLanguage. It reaches the wire for ONE of the fourteen types — RISC gives the reason members to credential-compromise and to nothing else — and is dropped by the catalogue on any other, rather than being sent as a member the specification does not define. |
|
reason_user |
string | The same, in words meant for the person. Same one type. | |
type |
string | yes | The event type: a short name such as account-disabled, or the whole URI. |
200: How many streams took it, why none did, or that the opt-out gate suppressed it.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
reports |
list | ||
reports[].claims |
any JSON | A Security Event Token’s claims. An event’s members are each event type’s, and the claims are what was signed, so a model of them here would be a second list of every event type. A Security Event Token’s claims. An event’s members are each event type’s, and the claims are what was signed, so a model of them here would be a second list of every event type. | |
reports[].deadLettered |
boolean | ||
reports[].delivered |
boolean | ||
reports[].err |
string, or null | ||
reports[].held |
boolean | ||
reports[].jti |
string | ||
reports[].ok |
boolean | ||
reports[].status |
integer, or null | ||
reports[].token |
string | ||
reports[].why |
string, or null | ||
warnings |
list | ||
warnings[] |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
reports |
list | ||
reports[].claims |
any JSON | A Security Event Token’s claims. An event’s members are each event type’s, and the claims are what was signed, so a model of them here would be a second list of every event type. A Security Event Token’s claims. An event’s members are each event type’s, and the claims are what was signed, so a model of them here would be a second list of every event type. | |
reports[].deadLettered |
boolean | ||
reports[].delivered |
boolean | ||
reports[].err |
string, or null | ||
reports[].held |
boolean | ||
reports[].jti |
string | ||
reports[].ok |
boolean | ||
reports[].status |
integer, or null | ||
reports[].token |
string | ||
reports[].why |
string, or null | ||
warnings |
list | ||
warnings[] |
string |
POST /admin-api/risc/reset-account
resetRiscAccount
Put one account’s RISC state back to where it started
Clears the lifecycle, the credential standing, the identifier history and every counter on one row, keeping the row. The opt state (RISC section 2.8) is KEPT: it is the account holder’s choice, and a pending opt-out still becomes effective on schedule.
IT DISABLES AND DELETES NOBODY. This register is a record of what has been SAID about an account; resetting it forgets the record. The directory entry is untouched, which is the distinction this whole page rests on — and it is sharper here than for a session, because a row saying purged may describe a person who really is gone.
Mirrors POST /admin/risc 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 |
|---|---|---|---|
account_id |
string | yes | The account. |
200: Confirmation, or a refusal naming the id.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |