This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.
A refusal
Unless an operation below says otherwise, any status it does not list answers this:
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | ||
status |
integer | ||
why |
string |
GET /admin-api/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 |