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

Management API

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/attribute-sources

getAttributeSources

The SQL databases this realm reads people’s attributes from (#94)

Everything /admin/attribute-sources draws: each source (its database, the row it reads, the columns it writes onto which attributes, when it reads and what a failure does) with its status, and the rules a definition is held to. Never a password.

Mirrors GET /admin/attribute-sources on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
sourcesPage query integer   Which page of sources to return, answered by sourcesPaging (#313).
per query integer   Rows per page. Capped, like every list here.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The register.

Member Type Required What it is
dialects list    
dialects[] string    
hostPatterns string    
job string    
modes list    
modes[] string    
onFailure list    
onFailure[] string    
passwordProviders list    
passwordProviders[] string    
refused object    
refused.names list    
refused.names[] string    
refused.prefixes list    
refused.prefixes[] 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, or null    
settings.editableCount integer    
settings.groups list    
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   The sentence beside each value.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list    
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or boolean, or number, or string, or null    
settings.groups[].settings[].default[] string    
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    
settings.groups[].settings[].env string, or null    
settings.groups[].settings[].group string    
settings.groups[].settings[].key string    
settings.groups[].settings[].label string    
settings.groups[].settings[].legacyEnv string, or null    
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 map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings.groups[].settings[].selectAll.{key} list    
settings.groups[].settings[].selectAll.{key}[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].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 boolean, or number, or string, or null    
settings.groups[].settings[].value[] string    
settings.overridden list    
settings.overridden[] string    
settings.page string    
settings.setWith string    
settings.settingCount integer    
settings.sharedWith map   The other pages, by settings group.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string    
settings.sharedWith.{key}[].path string    
sources list    
sources[].caCertificates string    
sources[].caFile string    
sources[].columns map   The attribute each column of the operator’s table is written onto.
sources[].columns.{key} string    
sources[].database string    
sources[].dialect string    
sources[].enabled boolean    
sources[].host string    
sources[].id string    
sources[].keyAttribute string    
sources[].keyColumn string    
sources[].onFailure string    
sources[].passwordField string    
sources[].passwordProvider string    
sources[].passwordRef string    
sources[].port number    
sources[].refresh list    
sources[].refresh[] string    
sources[].scheduleS number    
sources[].serverName string    
sources[].status object    
sources[].status.cursor string    
sources[].status.cursorKind string    
sources[].status.cursorOpen boolean    
sources[].status.cycleEndedAt number, or string, or null    
sources[].status.failures number    
sources[].status.lastCode string    
sources[].status.lastError string    
sources[].status.lastErrorAt string    
sources[].status.lastOkAt string    
sources[].status.lastRunAt string    
sources[].status.lastRunPeople number    
sources[].table string    
sources[].timeoutMs number    
sources[].trust object    
sources[].trust.caFile string    
sources[].trust.certificates list    
sources[].trust.certificates[].ca boolean    
sources[].trust.certificates[].expired boolean    
sources[].trust.certificates[].issuer string    
sources[].trust.certificates[].notAfter string    
sources[].trust.certificates[].notBefore string    
sources[].trust.certificates[].notYetValid boolean    
sources[].trust.certificates[].selfSigned boolean    
sources[].trust.certificates[].sha256 string    
sources[].trust.certificates[].subject string    
sources[].trust.publicRoots boolean    
sources[].trust.unreadable number    
sources[].trustPublicRoots boolean    
sources[].user string    
sourcesPaging object    
sourcesPaging.firstRow integer    
sourcesPaging.lastRow integer    
sourcesPaging.noun string, or null    
sourcesPaging.page integer    
sourcesPaging.pages integer    
sourcesPaging.param string, or null    
sourcesPaging.perPage integer    
sourcesPaging.total integer    

POST /admin-api/attribute-sources/add-source

addAttributeSource

Add an attribute source

A database this realm reads people’s attributes from. Refused for an attribute another source writes, one no outside source may write, a host attributeSources.hostPatterns does not allow, or a name that is not an identifier. Audited.

Mirrors POST /admin/attribute-sources 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
caCertificates string   The database’s trust chain as PEM certificates, stored with the source. Trusted ALONE unless trustPublicRoots; with no chain and no caFile, the public roots are used. An empty string clears it. A block that does not parse, or an expired certificate, is refused.
caFile string   A PEM file of CA certificates on this service’s disk, added to caCertificates. TLS is always verified.
columns map yes { “<column>”: “<directory attribute>” }. No attribute this service keeps, no identity or group membership, no mail; an attribute has one source.
columns.{key} string    
database string yes  
dialect one of postgres, mysql yes PostgreSQL, or MySQL / MariaDB.
enabled boolean    
host string yes The database host; attributeSources.hostPatterns may narrow it.
id string yes The source’s id in this realm.
keyAttribute string   The person’s attribute the key column holds (uid, employeeNumber, entryUUID…).
keyColumn string yes  
onFailure one of keep, refuse   keep: the stored values stand and the sign-in proceeds; refuse: the sign-in is refused.
passwordField string   The field, where the secret is a JSON object.
passwordProvider one of none, file, aws, gcp, azure, vault   Where the password is read from, through common/secrets.js; never stored here.
passwordRef string   A path (file) or a secret’s name; empty is the key-encryption key’s location.
port integer    
refresh list   When a person is read.
refresh[] one of once, sign-in, schedule, on-demand    
scheduleS integer   The scheduled refresh’s interval.
serverName string   The name the certificate is checked against; the host when empty.
table string yes A table or view, optionally schema.table.
timeoutMs integer    
trustPublicRoots boolean   Trust node’s public roots beside caCertificates. Off by default.
user string yes  

200: The source as stored.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

POST /admin-api/attribute-sources/refresh-person

refreshAttributeSourcePerson

Read one person from the sources now

From every source that allows on-demand, or the one named by id. Audited.

Mirrors POST /admin/attribute-sources 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
id string   The source’s id in this realm.
username string yes  

200: What changed, and which sources failed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

POST /admin-api/attribute-sources/refresh-source

refreshAttributeSource

Read every person from a source now

Queues the scheduled refresh for this source, which reads the realm’s people a page at a time. Audited.

Mirrors POST /admin/attribute-sources 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
id string yes The source’s id in this realm.

200: The scheduler run, in runId.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

POST /admin-api/attribute-sources/remove-source

removeAttributeSource

Remove an attribute source

It leaves the register; what it wrote on people’s entries stays. Audited.

Mirrors POST /admin/attribute-sources 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
id string yes The source’s id in this realm.

200: What was removed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

POST /admin-api/attribute-sources/test-source

testAttributeSource

Connect to a source and read one row, writing nothing

Reads the row for a person (by username, whose key attribute is used) or for a key given outright, and returns it. Nothing is written.

Mirrors POST /admin/attribute-sources 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
id string yes The source’s id in this realm.
key string    
username string    

200: found and the row.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

POST /admin-api/attribute-sources/update-source

updateAttributeSource

Change an attribute source

The members given replace the source’s; the rest are kept. Checked as add-source is. Audited.

Mirrors POST /admin/attribute-sources 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
caCertificates string   The database’s trust chain as PEM certificates, stored with the source. Trusted ALONE unless trustPublicRoots; with no chain and no caFile, the public roots are used. An empty string clears it. A block that does not parse, or an expired certificate, is refused.
caFile string   A PEM file of CA certificates on this service’s disk, added to caCertificates. TLS is always verified.
columns map   { “<column>”: “<directory attribute>” }. No attribute this service keeps, no identity or group membership, no mail; an attribute has one source.
columns.{key} string    
database string    
dialect one of postgres, mysql   PostgreSQL, or MySQL / MariaDB.
enabled boolean    
host string   The database host; attributeSources.hostPatterns may narrow it.
id string yes The source’s id in this realm.
keyAttribute string   The person’s attribute the key column holds (uid, employeeNumber, entryUUID…).
keyColumn string    
onFailure one of keep, refuse   keep: the stored values stand and the sign-in proceeds; refuse: the sign-in is refused.
passwordField string   The field, where the secret is a JSON object.
passwordProvider one of none, file, aws, gcp, azure, vault   Where the password is read from, through common/secrets.js; never stored here.
passwordRef string   A path (file) or a secret’s name; empty is the key-encryption key’s location.
port integer    
refresh list   When a person is read.
refresh[] one of once, sign-in, schedule, on-demand    
scheduleS integer   The scheduled refresh’s interval.
serverName string   The name the certificate is checked against; the host when empty.
table string   A table or view, optionally schema.table.
timeoutMs integer    
trustPublicRoots boolean   Trust node’s public roots beside caCertificates. Off by default.
user string    

200: The source as stored.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed list    
changed[] string    
errors list    
errors[] string    
failures list    
failures[].source string    
failures[].why string    
found boolean    
key string    
message string    
ok boolean yes  
row map   The row, by the operator’s column names.
row.{key} any JSON   A value of the operator’s own SQL table, as its driver read it. A value of the operator’s own SQL table, as its driver read it.
runId number, or string    
source object    
source.caCertificates string    
source.caFile string    
source.columns map   The attribute each column of the operator’s table is written onto.
source.columns.{key} string    
source.database string    
source.dialect string    
source.enabled boolean    
source.host string    
source.id string    
source.keyAttribute string    
source.keyColumn string    
source.onFailure string    
source.passwordField string    
source.passwordProvider string    
source.passwordRef string    
source.port number    
source.refresh list    
source.refresh[] string    
source.scheduleS number    
source.serverName string    
source.table string    
source.timeoutMs number    
source.trustPublicRoots boolean    
source.user string    
why string    

GET /admin-api/post-login-activities

getPostLoginActivities

Started post-login activities in this realm (#1111)

Everything Directory → Post-login activities draws: started, every post-login activity started in the realm, newest first — id, activity, groups (their DNs; empty for the whole realm), intervalDays, maxMails, perRun, state (running, paused, ended), who started and last changed it and when — each with run, what its scheduler job has done (passes over the population, read, mailed, notDue, heldBack, refused, lastRunAt, lastSummary); the activities an administrator may start, the limits of the numbers and of groups, whether a mail transport is mailAvailable, whether any post-login profile is activityEnabled (the POLICY asking anybody by itself; a running started activity asks its own people at sign-in whatever it says, #1126), the job and how often it runs; and groupChooser, the start form’s group search (#1123): chosen (the groups asked, each resolved — found false for a name this realm does not have) and pane, one page of the groups whose cn or DN contains groupq, 20 from groupfrom (a stale offset is clamped to the first page), the chosen ones left out (total, matched, from, shown: each dn and cn). The search reads the directory’s group index, never its people. Who was mailed and where each person stands is the reports application’s postLoginProgress source, not this operation.

Mirrors GET /admin/post-login-activities on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
groupq query string   The group search: a substring of a group’s cn or DN, case-insensitive; empty for every group.
groupfrom query string   Where the page of the group search starts.
groups query string   The groups chosen so far, cns or DNs separated by ; (a DN’s commas stay intact; a ; inside a DN value is escaped, \;); resolved into groupChooser.chosen and left out of the search. At most 4096 characters, which is as much as one request line can carry; fifty ordinary group names fit.
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 started activities and the chooser.

Member Type Required What it is
activities list    
activities[] string    
activityEnabled boolean    
everyMinutes number    
groupChooser object    
groupChooser.chosen list    
groupChooser.chosen[].asked string    
groupChooser.chosen[].cn string, or null    
groupChooser.chosen[].dn string, or null    
groupChooser.chosen[].found boolean    
groupChooser.pane object    
groupChooser.pane.from number    
groupChooser.pane.matched number    
groupChooser.pane.shown list    
groupChooser.pane.shown[].cn string, or null    
groupChooser.pane.shown[].dn string    
groupChooser.pane.total number    
groupChooser.search string    
job string    
limits object    
limits.groups object    
limits.groups.max number    
limits.intervalDays object    
limits.intervalDays.dflt number    
limits.intervalDays.max number    
limits.intervalDays.min number    
limits.maxMails object    
limits.maxMails.dflt number    
limits.maxMails.max number    
limits.maxMails.min number    
limits.perRun object    
limits.perRun.dflt number    
limits.perRun.max number    
limits.perRun.min number    
mailAvailable boolean    
realm string    
started list    
started[].activity string    
started[].changedAt number, or string, or null    
started[].changedBy string, or null    
started[].endedAt number, or string, or null    
started[].groups list    
started[].groups[] string    
started[].id string    
started[].intervalDays number    
started[].maxMails number    
started[].perRun number    
started[].run object    
started[].run.cursor string    
started[].run.heldBack number    
started[].run.lastRunAt string, or null    
started[].run.lastSummary string    
started[].run.mailed number    
started[].run.notDue number    
started[].run.passes number    
started[].run.read number    
started[].run.refused number    
started[].startedAt number, or string, or null    
started[].startedBy string, or null    
started[].state string    

POST /admin-api/post-login-activities/end

endPostLoginActivity

End a started post-login activity

A running or paused post-login activity ends for good: it asks nobody at sign-in and mails nobody again, and what it did stays on the page and on each person’s progress row. STS-AUTHN-0491 for no such started activity or one already ended.

Mirrors POST /admin/post-login-activities 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
id string yes The started activity.

200: The post-login activity ended.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state 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  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state string    

POST /admin-api/post-login-activities/pause

pausePostLoginActivity

Pause a started post-login activity

A running post-login activity stops asking at sign-in and stops mailing, within the slice a run is in; its cursor is kept. A person the post-login policy itself switches on is still asked. STS-AUTHN-0491 for no such started activity or one that is not running.

Mirrors POST /admin/post-login-activities 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
id string yes The started activity.

200: The post-login activity paused.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state 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  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state string    

POST /admin-api/post-login-activities/resume

resumePostLoginActivity

Resume a paused post-login activity

A paused post-login activity asks at sign-in again, and mails again from where its cursor stopped. STS-AUTHN-0491 for no such started activity or one that is not paused.

Mirrors POST /admin/post-login-activities 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
id string yes The started activity.

200: The post-login activity running again.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state 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  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state string    

POST /admin-api/post-login-activities/start

startPostLoginActivity

Start a post-login activity

Starts a post-login activity in this realm. AT SIGN-IN, from now, each person it reaches is asked to do it (#1126), under the rules of the post-login profile that reaches them — even where that profile is off, unless it is a NAMED profile that is off, which excludes them. BY MAIL, from the next run of the scheduler job post-login.activity-mail (every few minutes, or Run now on Monitoring → Scheduler) each person the activity is DUE for — it reaches them, the realm can make the passkey, they have not done it — is mailed at the address on their entry a reminder to sign in, at most maxMails times and never twice inside intervalDays. The mail’s one link opens the sign-in page; it carries no credential, and the post-login activity does the registration. groups narrows the people to the members of those groups: their UNION, a person in two of them read and mailed once; none means everybody in the realm. A group this realm does not have is refused (STS-AUTHN-0530); a second started activity for the same activity and the same groups is refused (STS-AUTHN-0492); bad values are STS-AUTHN-0490.

Mirrors POST /admin/post-login-activities 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)

Member Type Required What it is
activity one of pqc-passkey-migration   The post-login activity.
groups list   Groups’ cns or DNs, the people being the union of their members; empty or absent for everybody in the realm.
groups[] string    
intervalDays integer   Days between two mails to one person (default 7).
maxMails integer   The most mails one person is sent (default 3).
perRun integer   People read per run of the job (default 1000).

200: The post-login activity started.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state 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  
started object    
started.activity string    
started.changedAt number, or string, or null    
started.changedBy string, or null    
started.endedAt number, or string, or null    
started.groups list    
started.groups[] string    
started.id string    
started.intervalDays number    
started.maxMails number    
started.perRun number    
started.startedAt number, or string, or null    
started.startedBy string, or null    
started.state string    

GET /admin-api/secret-destinations

getSecretDestinations

Where this realm pushes service accounts’ rotated passwords (#221)

Everything Directory → Secret destinations draws: each destination (an application entry declared for the secret-destination family) with its provider, payload, location, whether a write credential is set, and whether it is usable and why not; the providers and payloads offered, and what each provider’s credential is. NEVER a credential.

Mirrors GET /admin/secret-destinations on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Narrows destinations to those whose name, identifier, DN or provider contains this, case-insensitively — the person page’s push destination search (#602). matched counts them.
destinationsPage query integer   Which page of destinations to return, answered by destinationsPaging (#313).
per query integer   Rows per page. Capped, like every list here.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The register.

Member Type Required What it is
credentialShapes map   What each provider’s credential is.
credentialShapes.{key} string    
destinations list    
destinations[].credentialSet boolean    
destinations[].credentialShape string    
destinations[].id string    
destinations[].identifier string    
destinations[].location object    
destinations[].location.caCertificates string    
destinations[].location.directory string    
destinations[].location.endpoint string    
destinations[].location.field string    
destinations[].location.mount string    
destinations[].location.payload string    
destinations[].location.project string    
destinations[].location.provider string    
destinations[].location.region string    
destinations[].name string    
destinations[].payload string    
destinations[].problems list    
destinations[].problems[] string    
destinations[].provider string    
destinations[].usable boolean    
destinationsPaging object    
destinationsPaging.firstRow integer    
destinationsPaging.lastRow integer    
destinationsPaging.noun string, or null    
destinationsPaging.page integer    
destinationsPaging.pages integer    
destinationsPaging.param string, or null    
destinationsPaging.perPage integer    
destinationsPaging.total integer    
family string    
fileAllowed boolean    
matched integer    
payloads list    
payloads[] string    
providers list    
providers[] string    

POST /admin-api/secret-destinations/add-destination

addSecretDestination

Add a secret push destination

Creates an application entry declared for the secret-destination family, with its location and its write credential (sealed, write-only). Refused for an unknown provider or payload, a missing location, a credential that is not its provider’s shape, a plain http address, or a file in product mode. Audited, without the credential.

Mirrors POST /admin/secret-destinations 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
caCertificates string   vault: PEM certificates of the CA its listener chains to.
credential string   The WRITE credential, write-only: never returned, drawn or logged. aws: JSON {accessKeyId, secretAccessKey[, sessionToken]}; gcp: a service account key’s JSON; azure: JSON {tenantId, clientId, clientSecret}; vault: a token. On a change, empty keeps the one set.
directory string   file: the absolute directory a secret name is a file in.
endpoint string   azure: the vault URL; vault: its address. https only.
field string   vault, password payload: the field written; value when empty.
identifier string yes The destination’s application identifier (add only): the entry it is filed under in ou=applications.
mount string   vault: the KV version 2 mount; secret when empty.
name string   What to call it on a page.
payload one of password, json   password (the bare password) or json ({username, password, realm, rotatedAt}).
project string   gcp: the project a short secret name is in.
provider one of aws, gcp, azure, vault, file yes aws, gcp, azure, vault, or file (development mode only).
region string   aws: the region.

200: The destination as the register now answers it.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null    

POST /admin-api/secret-destinations/remove-destination

removeSecretDestination

Remove a secret push destination

Deletes its application entry, credential and all. Nothing at the secrets manager changes. Audited.

Mirrors POST /admin/secret-destinations 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
id string yes The destination: its entry’s DN, as the register answers it, or its identifier.

200: What was removed.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null    

POST /admin-api/secret-destinations/test-push

testSecretDestination

Write a canary version to a test secret

Writes a random password nobody uses, as the destination’s payload, to secretName — which must already exist and must be kept for testing: a secret a service account’s rotation writes is refused. Proves the credential, the address and the secret. Audited.

Mirrors POST /admin/secret-destinations 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
id string yes The destination: its entry’s DN, as the register answers it, or its identifier.
secretName string yes The test secret.

200: ok and the version the store answered, or a coded refusal.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null    

POST /admin-api/secret-destinations/update-destination

updateSecretDestination

Change a secret push destination

The members given replace the destination’s; the rest are kept, the credential included when none is given. Checked as add-destination is. Audited, without the credential.

Mirrors POST /admin/secret-destinations 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
caCertificates string   vault: PEM certificates of the CA its listener chains to.
credential string   The WRITE credential, write-only: never returned, drawn or logged. aws: JSON {accessKeyId, secretAccessKey[, sessionToken]}; gcp: a service account key’s JSON; azure: JSON {tenantId, clientId, clientSecret}; vault: a token. On a change, empty keeps the one set.
directory string   file: the absolute directory a secret name is a file in.
endpoint string   azure: the vault URL; vault: its address. https only.
field string   vault, password payload: the field written; value when empty.
id string yes The destination: its entry’s DN, as the register answers it, or its identifier.
mount string   vault: the KV version 2 mount; secret when empty.
name string   What to call it on a page.
payload one of password, json   password (the bare password) or json ({username, password, realm, rotatedAt}).
project string   gcp: the project a short secret name is in.
provider one of aws, gcp, azure, vault, file   aws, gcp, azure, vault, or file (development mode only).
region string   aws: the region.

200: The destination as the register now answers it.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
destination object    
destination.credentialSet boolean    
destination.credentialShape string    
destination.id string    
destination.identifier string    
destination.location object    
destination.location.caCertificates string    
destination.location.directory string    
destination.location.endpoint string    
destination.location.field string    
destination.location.mount string    
destination.location.payload string    
destination.location.project string    
destination.location.provider string    
destination.location.region string    
destination.name string    
destination.payload string    
destination.problems list    
destination.problems[] string    
destination.provider string    
destination.usable boolean    
errors list    
errors[] string    
message string    
ok boolean yes  
version number, or string, or null