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/announcements

getConsoleAnnouncements

Announcements the console’s receiver took in

What an open console tab collects (#1086): the announcements this realm’s admin-console receiver took in after since — the now this operation answered the tab’s FIRST ask with — and within ssf.announcementKeepS, oldest first. With no since it answers only now, so a tab shows what arrived after it signed in. everyMs is how often to ask again.

Mirrors no console page — the announcement banner every console page draws, fed by POST /admin/broadcast (#1086) on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
since query integer   The now of the first answer, in milliseconds.
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: now, everyMs and announcements.

Member Type Required What it is
announcements list    
announcements[].at string    
announcements[].id string    
announcements[].message string    
everyMs number    
now number    

GET /admin-api/broadcast

getBroadcast

What an announcement can reach from this realm

The applications an announcement can be shown in (surfaces: id and label — the admin console, the user portal and the reports application, this service’s own Shared Signals receivers), whether the caller may send to everyRealm (a service administrator in the default realm), the longest message (maxChars), how often an open tab checks (pollMs), and whether anything can be delivered (ready, with why when not). Sending is POST /admin-api/broadcast/send.

Mirrors GET /admin/broadcast 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 broadcast view.

Member Type Required What it is
everyRealm boolean    
keepS number    
maxChars number    
pollMs number    
ready boolean    
realm string    
realmCount integer    
surfaces list    
surfaces[].id string    
surfaces[].label string    
why string    

POST /admin-api/broadcast/send

sendBroadcast

Show an announcement to everybody signed in

Sends this service’s own announcement Security Event Token on the receiver streams of the chosen applications, and every tab of them open at the time shows message in a banner within ssf.internalPollMs + ssf.announcementPollMs. A tab opened later does not. everyRealm sends it in every realm, and is refused (STS-SSF-0153) to anybody but a service administrator in the default realm. Answers how many streams took it per realm; sent: 0 with why (STS-SSF-0154) when none did.

Mirrors POST /admin/broadcast 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
everyRealm boolean   Every realm, not only this one.
message string yes Plain text, at most ssf.announcementMaxChars characters.
surfaces list yes Which applications show it.
surfaces[] one of admin-console, user-portal, report    

200: How many receiver streams took it.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
realms list    
realms[].realm string    
realms[].sent integer    
realms[].skipped list    
realms[].skipped[] string    
realms[].streams integer    
sent integer    
streams integer    
why 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  
realms list    
realms[].realm string    
realms[].sent integer    
realms[].skipped list    
realms[].skipped[] string    
realms[].streams integer    
sent integer    
streams integer    
why string    

GET /admin-api/signals

getSignals

Every security event delivered TO this console

This service’s own admin console is a registered Shared Signals receiver: it has a stream of its own (sts-admin-console), seeded in EVERY trust realm, asking for every CAEP and every RISC event type, and each event is POSTed to it over RFC 8935 push at /admin/signals/receive with that stream’s own bearer token. This is what arrived.

IT IS SEEDED IN EVERY REALM AND THE CONSOLE’S CLIENT ENTRY IS IN ONE, and the disagreement is deliberate: a client entry is about signing somebody IN, and this console’s gate reads the DEFAULT realm’s session wherever it is reached; a stream is about what HAPPENED, and events happen in the realm they happen in.

READ status.why BEFORE CONCLUDING NOTHING HAS HAPPENED. An empty received has five causes and only one of them is that: ssf.enabled off, ssf.internalReceivers off, the stream deleted (it is an ORDINARY stream — delete it here or at /admin/ssf and it stays deleted until a restart), ssf.pushDelivery off, or caep.enabled / risc.enabled off under it.

WHAT A PERSON SEES IS A DIFFERENT RECEIVER. The user portal has a stream of its own and shows each person only the events whose subject is them; there is no operation here for that view, because it is a person’s own page and not an administrative one.

The inbox is IN MEMORY, per trust realm, capped at ssf.maxReceivedEvents. The durable record of every delivery is GET /admin-api/audit, which cannot be cleared.

Mirrors GET /admin/signals on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
sigq query string   Narrows the list to rows whose event name, type URI, subject, issuer, audience, jti or stream id contains this. One box over all of them, because a reader arrives holding one and does not know which column it is in.
receivedPage query integer   Which page of the delivered events. Clamped, like every page parameter here.
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: This receiver and its stream, and the delivered events.

Member Type Required What it is
filter object    
filter.received string, or null    
paging object    
paging.received object    
paging.received.firstRow integer    
paging.received.lastRow integer    
paging.received.noun string    
paging.received.page integer    
paging.received.pages integer    
paging.received.param string    
paging.received.perPage integer    
paging.received.total integer    
received list    
received[].at string, or number, or null    
received[].audience string    
received[].audienceOk boolean    
received[].contentType string, or null    
received[].correctMediaType boolean    
received[].issuer string    
received[].jti string    
received[].name string    
received[].payload any JSON   An event’s body as this receiver took it in: each event type has its own members, and a refused delivery is held here too. An event’s body as this receiver took it in: each event type has its own members, and a refused delivery is held here too.
received[].problem string    
received[].reactions list    
received[].reactions[].ended integer    
received[].reactions[].event string    
received[].reactions[].failed boolean    
received[].reactions[].observed boolean    
received[].reactions[].reaction string    
received[].reactions[].revoked integer    
received[].reactions[].skipped string    
received[].stream string, or null    
received[].subject string    
received[].surface string, or null    
received[].tokenDigest string    
received[].types list    
received[].types[] string    
received[].verificationNote string, or null    
received[].verified boolean    
received[].vocabulary string    
status object    
status.audience string    
status.caepEnabled boolean    
status.enabled boolean    
status.held integer    
status.id string    
status.inboxPath string    
status.internalReceivers boolean    
status.label string    
status.max number    
status.pushDelivery boolean    
status.realm string    
status.receivePath string    
status.riscEnabled boolean    
status.sees string    
status.ssfEnabled boolean    
status.stream object    
status.stream.aud list, or string, or null    
status.stream.aud[] string    
status.stream.caepDelivered integer    
status.stream.counters map    
status.stream.counters.{key} number    
status.stream.delivers integer    
status.stream.delivery string    
status.stream.endpoint_url string    
status.stream.iss string, or null    
status.stream.lastPushAt string, or number, or null    
status.stream.lastPushError string, or null    
status.stream.pollEveryMs number    
status.stream.queued integer    
status.stream.requested integer    
status.stream.riscDelivered integer    
status.stream.status string    
status.stream.statusReason string, or null    
status.stream.stream_id string    
status.why list    
status.why[] string    
total integer    

POST /admin-api/signals/clear

clearSignalsInbox

Empty the console’s Shared Signals inbox

Drops every delivered event held for the admin console in this trust realm.

IT DOES NOT TOUCH THE STREAM. Clearing what a receiver has been shown and tearing down the agreement to send it more are two different acts; the second one is POST /admin-api/ssf/delete-stream. This receiver goes on taking delivery the moment this returns.

AND IT DOES NOT TOUCH THE RECORD. Every delivery wrote an ssf.event.receive row to the audit log, which has no clear operation anywhere — which is what makes it the durable half.

Mirrors POST /admin/signals 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 delivered events were dropped.

Member Type Required What it is
dropped integer    
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
dropped integer    
errors list    
errors[] string    
message string    
ok boolean yes  

GET /admin-api/ssf

getSsf

The Shared Signals transmitter: its streams, their subjects, their queues and what a receiver refused

Everything /admin/ssf draws, as JSON. Per stream: the configuration a receiver agreed, who it is about, what is waiting to be delivered, the counters, and the stream’s own log — which is the only place a REFUSED PUSH is recorded, because a push a receiver rejected is invisible from the receiving end by definition.

SSF IS THE PIPE AND NOT THE VOCABULARY. It defines how two parties agree a stream, who the events are about (RFC 9493), what they travel in (RFC 8417) and how they get there (RFC 8935 push, RFC 8936 poll) — and two events of its own, both about the pipe. CAEP and RISC are the vocabularies spoken over it; CAEP is implemented and its own register is at GET /admin-api/caep, and RISC has one of its own at GET /admin-api/risc.

THE RECEIVER’S authorization_header IS NOT IN THIS REPLY. It is a credential belonging to somebody else’s endpoint and it goes back only to the receiver that set it, at GET /ssf/stream.

Mirrors GET /admin/ssf on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
stream query string   Only this stream. An exact stream id; applied before the streams are paged.
streamsPage query integer   Which page of the streams. Clamped, like every page parameter here.
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 transmitter, its streams and what it has received.

Member Type Required What it is
authentication object    
authentication.metadataIsOpen boolean    
authentication.note string    
authentication.passwordVerified boolean    
authentication.realm string    
authentication.refusedPassword string    
authentication.required boolean    
authentication.schemes list    
authentication.schemes[].id string    
authentication.schemes[].name string    
authentication.schemes[].offered boolean    
authentication.schemes[].spec_urn string    
authentication.schemes[].what string    
authentication.scopes object    
authentication.scopes.read string    
authentication.scopes.readAlso list    
authentication.scopes.readAlso[] string    
authentication.scopes.write string    
authentication.scopes.writeAlso list    
authentication.scopes.writeAlso[] string    
authentication.scopes.writeIncludesRead boolean    
complexSubjectMembers list    
complexSubjectMembers[].name string    
complexSubjectMembers[].what string    
criticalSubjectMembers list    
criticalSubjectMembers[] string    
deadLetters object    
deadLetters.deadStreamTimeoutS number    
deadLetters.maxPerStream number    
deadLetters.pushes object    
deadLetters.pushes.active integer    
deadLetters.pushes.backlog number    
deadLetters.pushes.concurrency number    
deadLetters.pushes.waiting integer    
deadLetters.retentionS number    
delivery list    
delivery[].method string    
delivery[].name string    
delivery[].offered boolean    
delivery[].what string    
doesNotDo list    
doesNotDo[] string    
enabled boolean    
endpoints list    
endpoints[].method string    
endpoints[].path string    
endpoints[].what string    
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    
installed boolean    
issuer string    
metadata object    
metadata.add_subject_endpoint string    
metadata.authorization_schemes list    
metadata.authorization_schemes[].spec_urn string    
metadata.configuration_endpoint string    
metadata.critical_subject_members list    
metadata.critical_subject_members[] string    
metadata.default_subjects string    
metadata.delivery_methods_supported list    
metadata.delivery_methods_supported[] string    
metadata.issuer string    
metadata.jwks_uri string    
metadata.remove_subject_endpoint string    
metadata.spec_version string    
metadata.status_endpoint string    
metadata.verification_endpoint string    
metadataUrl string    
note string    
paging object    
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    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
push object    
push.allowed boolean    
push.allowedHosts list    
push.allowedHosts[] string    
push.maxResponseBytes number    
push.note string    
push.retries number    
push.transport object    
push.transport.allowHttp boolean    
push.transport.caFile string    
push.transport.skipTlsVerification boolean    
push.transport.skipTlsVerificationSet boolean    
reachableNegatives list    
reachableNegatives[].answer string    
reachableNegatives[].what string    
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    
signingAlgorithm string    
statuses list    
statuses[] string    
streamDetail list    
streamDetail[].aud list, or string, or null    
streamDetail[].aud[] string    
streamDetail[].counters map    
streamDetail[].counters.{key} number    
streamDetail[].createdAt string, or number, or null    
streamDetail[].createdBy string, or null    
streamDetail[].dead boolean    
streamDetail[].deadLetters list    
streamDetail[].deadLetters[].deadAt string, or number, or null    
streamDetail[].deadLetters[].errorCode string, or null    
streamDetail[].deadLetters[].jti string    
streamDetail[].deadLetters[].queuedAt string, or number, or null    
streamDetail[].deadLetters[].reason string, or null    
streamDetail[].deadLetters[].signed boolean    
streamDetail[].deadLetters[].status integer, or null    
streamDetail[].deadLetters[].summary object    
streamDetail[].deadLetters[].summary.audience list, or string    
streamDetail[].deadLetters[].summary.audience[] string    
streamDetail[].deadLetters[].summary.iat number    
streamDetail[].deadLetters[].summary.issuer string    
streamDetail[].deadLetters[].summary.jti string    
streamDetail[].deadLetters[].summary.name string    
streamDetail[].deadLetters[].summary.subject string    
streamDetail[].deadLetters[].summary.types list    
streamDetail[].deadLetters[].summary.types[] string    
streamDetail[].deadReason string    
streamDetail[].deadSince string    
streamDetail[].delivery object    
streamDetail[].delivery.endpoint_url string, or null    
streamDetail[].delivery.method string    
streamDetail[].description string, or null    
streamDetail[].events_delivered list    
streamDetail[].events_delivered[] string    
streamDetail[].events_requested list    
streamDetail[].events_requested[] string    
streamDetail[].failingSince string    
streamDetail[].format string, or null    
streamDetail[].internal boolean    
streamDetail[].iss string, or null    
streamDetail[].lastPushAt string, or number, or null    
streamDetail[].lastPushError string, or null    
streamDetail[].log list    
streamDetail[].log[].at string    
streamDetail[].log[].kind string    
streamDetail[].log[].text string    
streamDetail[].nextProbeAt string    
streamDetail[].queue list    
streamDetail[].queue[].deliveredAt string, or number, or null    
streamDetail[].queue[].jti string    
streamDetail[].queue[].queuedAt string, or number, or null    
streamDetail[].queue[].summary object    
streamDetail[].queue[].summary.audience list, or string    
streamDetail[].queue[].summary.audience[] string    
streamDetail[].queue[].summary.iat number    
streamDetail[].queue[].summary.issuer string    
streamDetail[].queue[].summary.jti string    
streamDetail[].queue[].summary.name string    
streamDetail[].queue[].summary.subject string    
streamDetail[].queue[].summary.types list    
streamDetail[].queue[].summary.types[] string    
streamDetail[].status string    
streamDetail[].statusReason string, or null    
streamDetail[].stream_id string    
streamDetail[].subjects list    
streamDetail[].subjects[].addedAt string, or number, or null    
streamDetail[].subjects[].subject any JSON   An RFC 9493 subject identifier, as a stream was given it or a person named it: the format decides the members, an aliases nests, and SSF 1.0 section 3.3 lets a receiver add its own. An RFC 9493 subject identifier, as a stream was given it or a person named it: the format decides the members, an aliases nests, and SSF 1.0 section 3.3 lets a receiver add its own.
streamDetail[].subjects[].text string    
streamDetail[].subjects[].verified boolean, or null    
streamDetail[].updatedAt string, or number, or null    
streamFilter string, or null    
streamTotals object    
streamTotals.dead integer    
streamTotals.deadLetters integer    
streamTotals.delivered number    
streamTotals.enabled integer    
streamTotals.failed number    
streamTotals.streams integer    
streamTotals.waiting integer    
streams list    
streams[].counters map    
streams[].counters.{key} number    
streams[].createdAt string, or number, or null    
streams[].delivery string    
streams[].events_delivered list    
streams[].events_delivered[] string    
streams[].lastPushError string, or null    
streams[].queued integer    
streams[].status string    
streams[].stream_id string    
streams[].subjects integer    
subjectFormats list    
subjectFormats[].example object    
subjectFormats[].example.assertion_id string    
subjectFormats[].example.email string    
subjectFormats[].example.format string    
subjectFormats[].example.id string    
subjectFormats[].example.identifiers list    
subjectFormats[].example.identifiers[].email string    
subjectFormats[].example.identifiers[].format string    
subjectFormats[].example.identifiers[].phone_number string    
subjectFormats[].example.ip-addresses list    
subjectFormats[].example.ip-addresses[] string    
subjectFormats[].example.iss string    
subjectFormats[].example.issuer string    
subjectFormats[].example.jti string    
subjectFormats[].example.phone_number string    
subjectFormats[].example.sub string    
subjectFormats[].example.uri string    
subjectFormats[].example.url string    
subjectFormats[].format string    
subjectFormats[].members list    
subjectFormats[].members[] string    
subjectFormats[].what string    

POST /admin-api/ssf/clear-dead-letters

clearSsfDeadLetters

Drop a stream’s dead letters

Empties the stream’s dead-letter queue: SETs that could not be delivered, each kept with its reason for ssf.deadLetterRetentionS. Nothing is sent. GET /admin-api/ssf lists them per stream as deadLetters.

Mirrors POST /admin/ssf 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
stream_id string yes The stream.

200: How many were dropped, or a refusal naming the stream_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  

GET /admin-api/ssf/dead-letters

getSsfDeadLetters

What the Shared Signals transmitter could not deliver, counted

Everything /admin/ssf/dead-letters draws, as JSON: every Security Event Token held on a dead-letter queue in this realm, counted by cause, error code, the receiver’s HTTP status and event type, over time across the retention window, and per stream with each push stream’s delivery state — then the letters themselves, newest first, searched and paged, without their tokens.

THE COUNTS ARE THE WHOLE REALM’S WHATEVER IS NARROWED. dlq, dlstream and dlcause narrow letters and matched only.

process IS THE ANSWERING PROCESS’S. Its push cap is shared by every realm in that process, and its sweeps are its own; the rest is the shared store.

Mirrors GET /admin/ssf/dead-letters on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
dlq query string   Narrows the letters to those whose jti, stream, reason, error code, status, event name, type URI or subject contains this.
dlstream query string   Only this stream’s letters. An exact stream id.
dlcause query one of push-failed, backlog-full, declared-dead, dead-stream   Only letters of this cause.
lettersPage query integer   Which page of the matched letters. Clamped, like every page parameter here.
streamsPage query integer   Which page of the streams holding a letter or not delivering, after dlstream and dlcause have narrowed them. It shares per with the letters.
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 dead-letter queues of this realm, counted, and a page of their letters.

Member Type Required What it is
byCode list    
byCode[].cause string    
byCode[].count integer    
byCode[].errorCode string    
byCode[].summary string    
byEventType list    
byEventType[].count integer    
byEventType[].name string    
byEventType[].type string    
byStatus list    
byStatus[].count integer    
byStatus[].status number    
causes list    
causes[].code string    
causes[].count integer    
causes[].id string    
causes[].label string    
causes[].what string    
enabled boolean    
filter object    
filter.cause string, or null    
filter.q string, or null    
filter.stream string, or null    
generatedAt string    
installed boolean    
letters list    
letters[].ageS number, or null    
letters[].cause string    
letters[].deadAt string, or number, or null    
letters[].errorCode string    
letters[].event object    
letters[].event.name string    
letters[].event.subject string    
letters[].event.types list    
letters[].event.types[] string    
letters[].jti string    
letters[].queuedAt string, or number, or null    
letters[].reason string    
letters[].signed boolean    
letters[].status number    
letters[].streamKnown boolean    
letters[].stream_id string    
matched integer    
note string    
paging object    
paging.letters object    
paging.letters.firstRow integer    
paging.letters.lastRow integer    
paging.letters.noun string    
paging.letters.page integer    
paging.letters.pages integer    
paging.letters.param string    
paging.letters.perPage integer    
paging.letters.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    
process object    
process.pid integer    
process.pushes object    
process.pushes.active integer    
process.pushes.backlog number    
process.pushes.concurrency number    
process.pushes.waiting integer    
process.role string    
process.sinceStart object    
process.sinceStart.expired number    
process.sinceStart.firstSweepAt string    
process.sinceStart.letters number    
process.sinceStart.orphaned number    
process.sinceStart.probes number    
process.sinceStart.sweeps number    
process.sinceStart.trimmed number    
process.sweeps list    
process.sweeps[].at string    
process.sweeps[].deadStreams integer    
process.sweeps[].expired integer    
process.sweeps[].held integer    
process.sweeps[].letters integer    
process.sweeps[].orphaned integer    
process.sweeps[].probes integer    
process.sweeps[].trimmed integer    
process.thread integer, or string, or null    
pushDelivery boolean    
realm string    
settings object    
settings.deadStreamTimeoutS number    
settings.maxPerStream number    
settings.pushBacklog number    
settings.pushConcurrency number    
settings.pushRetries number    
settings.retentionS number    
settings.sweepS number    
streams list    
streams[].aud list, or string, or null    
streams[].aud[] string    
streams[].causes map    
streams[].causes.{key} number    
streams[].deadLetteredEver number    
streams[].deadReason string    
streams[].deadSince string    
streams[].endpoint_url string    
streams[].failingSince string    
streams[].held integer    
streams[].lastPushAt string, or number, or null    
streams[].lastPushError string    
streams[].newestAt string    
streams[].nextProbeAt string    
streams[].oldestAt string    
streams[].state string    
streams[].status string    
streams[].stream_id string    
timeline object    
timeline.bucketS number    
timeline.buckets list    
timeline.buckets[].counts map    
timeline.buckets[].counts.{key} number    
timeline.buckets[].start string    
timeline.buckets[].startMs number    
timeline.buckets[].total integer    
timeline.from string    
timeline.olderThanWindow integer    
timeline.peak integer    
timeline.to string    
timeline.windowS number    
totals object    
totals.deadLetteredEver number    
totals.deadStreams integer    
totals.failingStreams integer    
totals.halfOpenStreams integer    
totals.held integer    
totals.newestAgeS number, or null    
totals.newestAt string    
totals.oldestAgeS number, or null    
totals.oldestAt string    
totals.pushStreams integer    
totals.signed integer    
totals.streamsHolding integer    
totals.unsigned integer    

400: The answer.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/ssf/delete

deleteSsfStream

Delete a stream

The stream, its subjects and everything queued on it. The receiver is NOT told — SSF has no event for “your stream is gone”, and a stream-updated with status disabled would be a lie about something that still exists. A receiver finds out on its next call, with a 404 naming the stream_id.

Mirrors POST /admin/ssf 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
stream_id string yes The stream.

200: Confirmation, or a refusal naming the stream_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  

POST /admin-api/ssf/revive

reviveSsfStream

Revive a dead push stream

A push stream whose pushes have all failed for ssf.deadStreamTimeoutS is declared DEAD: nothing more is pushed to it, its SETs go to its dead-letter queue, and a sweep pushes one as a probe every period. This revives it at once, so the next SET is pushed. Refused for a stream that is not dead. The dead letters are kept, and nothing resends them.

Mirrors POST /admin/ssf 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
reason string   Optional; written on the stream’s log.
stream_id string yes The stream.

200: Confirmation, or a refusal naming the stream_id or saying it is not dead.

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/ssf/status

setSsfStreamStatus

Enable, pause or disable a stream

The three values and what separates them: a PAUSED stream keeps QUEUEING and delivers nothing, so what happened while it was paused is still there when it is enabled again; a DISABLED one DROPS what is waiting. That is the difference between “I was not listening” and “it did not happen”, and it is the whole reason a Shared Signals receiver has a pause. A paused PUSH stream holds its SETs and pushes them, in order, when it is enabled again.

A change here also emits a stream-updated event ON the stream whether or not the receiver agreed that type (SSF 1.0 section 8.1.5), in the order that section requires: BEFORE the stream stops when it is paused or disabled, and after it starts again when it is enabled. Setting the status a stream already has announces nothing.

Mirrors POST /admin/ssf 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
reason string   Optional. Why, in words — it rides in the stream-updated event’s reason member, which nothing parses.
status one of enabled, paused, disabled yes The new status.
stream_id string yes The stream, as GET /admin-api/ssf lists it.

200: What happened, and whether the stream-updated event went with it.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
report object    
report.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.
report.deadLettered boolean    
report.delivered boolean    
report.err string, or null    
report.held boolean    
report.jti string    
report.ok boolean    
report.status integer, or null    
report.token string    
report.why string, or null    

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  
report object    
report.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.
report.deadLettered boolean    
report.delivered boolean    
report.err string, or null    
report.held boolean    
report.jti string    
report.ok boolean    
report.status integer, or null    
report.token string    
report.why string, or null    

POST /admin-api/ssf/transmit

transmitSsfEvent

Send a Security Event Token on a stream

Builds the SET, signs it with ssf.signingAlgorithm, queues it on the stream and — for a PUSH stream — POSTs it to the receiver’s delivery endpoint. On a POLL stream it stays queued until the receiver asks.

IT IS THE ONLY WAY AN EVENT HAPPENS HERE. Nothing in this service watches a session and emits when it changes: SSF defines no event about a session, so a transmitter that invented one would be inventing a vocabulary. That changes with CAEP.

A failed push is NOT retried and the event stays on the queue. A service that retried would make a receiver’s one-shot failure invisible — a client answering 500 then 202 looks, from its own logs, like a client that works.

Mirrors POST /admin/ssf 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
payload object   The event’s own members. A verification event takes an optional state; a stream-updated event takes a required status and an optional reason. An unrecognised member is CARRIED with a warning rather than refused: an event vocabulary extends, and a receiver is expected to ignore what it does not know.
stream_id string yes The stream.
subject object   Optional sub_id (RFC 9493), simple or complex. Neither SSF event takes one — both are about the STREAM — so this is here for the vocabularies that come next. Each format’s member set is CLOSED and an extra member is refused by name.
txn string   Optional RFC 8417 txn, tying several events to one act.
type string yes The event type URI. It must be one the stream DELIVERS — the intersection of what the receiver requested and what this transmitter supports — and a refusal lists what that is.

200: The jti, whether it was delivered or only queued, and what the receiver said.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
report object    
report.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.
report.deadLettered boolean    
report.delivered boolean    
report.err string, or null    
report.held boolean    
report.jti string    
report.ok boolean    
report.status integer, or null    
report.token string    
report.why string, or null    

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  
report object    
report.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.
report.deadLettered boolean    
report.delivered boolean    
report.err string, or null    
report.held boolean    
report.jti string    
report.ok boolean    
report.status integer, or null    
report.token string    
report.why string, or null    

GET /admin-api/ssf/transmitters

getPartnerSignals

The federation partners whose Shared Signals this realm receives

Everything /admin/ssf/transmitters draws: each federation relationship whose signals are on (its kind — sign-in or signals-only — SSF issuer, discovered configuration, delivery, stream, counts and blocks), every Security Event Token that arrived with whether it verified, the person it named and what it led to, the sign-ins partners have blocked and the account locks a signals-only partner put on people here. Never a secret. relationship narrows what arrived. What arrived, the blocks and the locks are each one page, moved by receivedPage, blocksPage and locksPage with per shared, and described by paging. A partner’s stream is configured on its relationship and acted on with POST /admin-api/federation/signals-*.

Mirrors GET /admin/ssf/transmitters on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
relationship query string   Only what arrived from this relationship. Applied before what arrived is paged.
receivedPage query integer   Which page of what arrived, newest first. Clamped, like every page parameter here.
blocksPage query integer   Which page of the sign-ins partners blocked.
locksPage query integer   Which page of the account locks partners put on people here.
per query integer   Rows per page, shared by the three lists.
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 report.

Member Type Required What it is
blocks list    
blocks[].at string    
blocks[].by string    
blocks[].event string    
blocks[].jti string    
blocks[].relationship string    
blocks[].username string    
counts object    
counts.blocks integer    
counts.locks integer    
counts.received integer    
locks list    
locks[].at string    
locks[].relationship string    
locks[].username string    
observeOnly boolean    
paging object    
paging.blocks object    
paging.blocks.firstRow integer    
paging.blocks.lastRow integer    
paging.blocks.noun string    
paging.blocks.page integer    
paging.blocks.pages integer    
paging.blocks.param string    
paging.blocks.perPage integer    
paging.blocks.total integer    
paging.locks object    
paging.locks.firstRow integer    
paging.locks.lastRow integer    
paging.locks.noun string    
paging.locks.page integer    
paging.locks.pages integer    
paging.locks.param string    
paging.locks.perPage integer    
paging.locks.total integer    
paging.received object    
paging.received.firstRow integer    
paging.received.lastRow integer    
paging.received.noun string    
paging.received.page integer    
paging.received.pages integer    
paging.received.param string    
paging.received.perPage integer    
paging.received.total integer    
received list    
received[].events list    
received[].events[] string    
received[].iat number    
received[].jti string    
received[].mapping string    
received[].person string    
received[].reactions list    
received[].reactions[].codes integer    
received[].reactions[].done boolean    
received[].reactions[].ended integer    
received[].reactions[].event string    
received[].reactions[].gnapGrants integer    
received[].reactions[].oauthGrants integer    
received[].reactions[].observed boolean    
received[].reactions[].reaction string    
received[].reactions[].revoked integer    
received[].reactions[].skipped string    
received[].reactions[].status string    
received[].reactions[].tokens integer    
received[].reactions[].why string    
received[].receivedAt string    
received[].refusal string    
received[].relationship string    
received[].subject any JSON   An RFC 9493 subject identifier as a partner’s SET carried it, in whatever format that partner chose. An RFC 9493 subject identifier as a partner’s SET carried it, in whatever format that partner chose.
received[].verified boolean    
received[].via string    
received[].why string    
relationships list    
relationships[].blocks list    
relationships[].blocks[].at string    
relationships[].blocks[].by string    
relationships[].blocks[].event string    
relationships[].blocks[].jti string    
relationships[].blocks[].relationship string    
relationships[].blocks[].username string    
relationships[].config object    
relationships[].config.add_subject_endpoint any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].config.configuration_endpoint any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].config.delivery_methods_supported list    
relationships[].config.delivery_methods_supported[] any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].config.issuer any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].config.jwks_uri any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].config.remove_subject_endpoint any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].config.status_endpoint any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].config.verification_endpoint any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].counts object    
relationships[].counts.acted integer    
relationships[].counts.received integer    
relationships[].counts.refused integer    
relationships[].counts.verified integer    
relationships[].credential object    
relationships[].credential.clientId string    
relationships[].credential.method string    
relationships[].credential.scope string    
relationships[].credential.secretHeld boolean    
relationships[].credential.tokenEndpoint string    
relationships[].delivery string    
relationships[].discoveredAt string    
relationships[].discoveryUrl string    
relationships[].enabled boolean    
relationships[].eventsRequested list    
relationships[].eventsRequested[] string    
relationships[].issuer string    
relationships[].kind string    
relationships[].lastError string    
relationships[].lastPollAt string    
relationships[].lastPollResult string    
relationships[].missing list    
relationships[].missing[] string    
relationships[].name string    
relationships[].pollEndpoint string    
relationships[].pushEndpoint string    
relationships[].pushEndpointSet boolean    
relationships[].ready boolean    
relationships[].receiving boolean    
relationships[].relationship string    
relationships[].signalsEnabled boolean    
relationships[].state string    
relationships[].stream object    
relationships[].stream.aud any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].stream.delivery object    
relationships[].stream.delivery.endpoint_url any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].stream.delivery.method any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].stream.events_delivered any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].stream.events_requested any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].stream.events_supported any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].stream.stream_id any JSON   A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure. A value of a document a partner published or answered, kept and relayed as it arrived: nothing here narrows it, and a partner’s odd value must not turn an operator’s own page into a failure.
relationships[].streamAud list    
relationships[].streamAud[] string    
relationships[].streamDelivery string    
relationships[].streamId string    
relationships[].streamStatus string    
relationships[].verifiedAt string    

POST /admin-api/ssf/verify

verifySsfStream

Send a transmitter-initiated verification event

SSF 1.0 section 8.1.4: a transmitter MAY send a verification event at any time. This sends one on the stream with NO state — section 8.1.4.2 forbids a state the receiver did not supply — whether or not the stream agreed the type. A paused push stream holds it until it is enabled; a disabled stream refuses it. ssf.verificationEveryS does the same on a schedule.

Mirrors POST /admin/ssf 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
stream_id string yes The stream.

200: Whether the event was delivered, queued for polling or held, or a refusal naming the stream_id or why it was not sent.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
report object    
report.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.
report.deadLettered boolean    
report.delivered boolean    
report.err string, or null    
report.held boolean    
report.jti string    
report.ok boolean    
report.status integer, or null    
report.token string    
report.why string, or null    

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  
report object    
report.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.
report.deadLettered boolean    
report.delivered boolean    
report.err string, or null    
report.held boolean    
report.jti string    
report.ok boolean    
report.status integer, or null    
report.token string    
report.why string, or null