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