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

Management API

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