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

getRealms

Every trust realm, its endpoints and what it sets

A TRUST REALM is a whole logical copy of this service: its own configuration, its own signing key, and its own sessions, authorization codes, tokens, credential offers, service providers, statistics and audit log — answering on the same sockets as every other realm and told apart by a segment at the front of the path.

The DEFAULT realm has no prefix, cannot be removed and cannot be renamed: every URL this service published before realms existed is a URL in it. A process with no realms defined behaves exactly as it did before this feature existed, which is a property of one predicate rather than a claim.

Each row carries the realm’s domain and baseDn, its pathPrefix, its baseUrl, the kid of its signing key — two realms showing one kid would be two names for one authorization server — the settings it sets, and the four discovery documents a client asks for first.

retiring is null, or says the realm is being REMOVED (#262, #294): since and sinceIso, whether the removal is inProgress or was interrupted (the process doing it stopped; every new sign-in and issuance in it is refused until it is finished), refusing, why and finish — for an interrupted one, POST /admin-api/realms/remove again, from another realm.

support is the part answered nowhere else: WHICH protocol families a realm actually separates, which is not a tidy answer. A realm separates what this service ISSUES and everything it holds while issuing it — keys, sessions, codes, tokens, offers, artifacts, statistics and the audit log. It does NOT separate the embedded directory: LDAP answers on a socket with no path to put a segment in, so there is one set of people, groups and applications for the whole process — which means OAuth client registrations, SAML service provider entries, the SPIFFE registry and the two admin console roles are shared. Kerberos, the certificate the main port and LDAPS 636 present, and SPIFFE’s four sockets are shared for the same reason.

reserved is the list of ids a realm may not be called, read off the live router: they are the first segments of paths this service already serves, and the refusal stands whatever realms.pathSegment is set to precisely so that clearing that setting cannot turn an existing realm into a shadow over the console or the authorization server.

Mirrors GET /admin/realms on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The realms, and the support table.

Member Type Required What it is
active boolean    
count integer    
current string    
currentName string    
defaultDomain string    
enabled boolean    
paging object   Which page of how many, and the query parameter that moves it.
paging.firstRow integer    
paging.lastRow integer    
paging.noun string    
paging.page integer    
paging.pages integer    
paging.param string    
paging.perPage integer    
paging.total integer    
pathSegment string    
persistence object    
persistence.mode string    
persistence.persistsRealms boolean    
realms list    
realms[].baseDn string    
realms[].baseUrl string    
realms[].builtin boolean    
realms[].description string, or null    
realms[].domain string    
realms[].endpoints object    
realms[].endpoints.authorizationServerMetadata string    
realms[].endpoints.jwks string    
realms[].endpoints.openidConfiguration string    
realms[].endpoints.samlMetadata string    
realms[].id string    
realms[].kid string, or null    
realms[].listeners list    
realms[].listeners[].certificateSource string    
realms[].listeners[].clientAuth string, or null    
realms[].listeners[].here object    
realms[].listeners[].here.boundAt string, or number, or null    
realms[].listeners[].here.certificate object    
realms[].listeners[].here.certificate.notAfter string    
realms[].listeners[].here.certificate.notBefore string    
realms[].listeners[].here.certificate.serialHex string    
realms[].listeners[].here.certificate.source string    
realms[].listeners[].here.hostnames list    
realms[].listeners[].here.hostnames[] string    
realms[].listeners[].here.id string    
realms[].listeners[].here.owner string    
realms[].listeners[].here.port integer    
realms[].listeners[].here.publicBaseUrl string, or null    
realms[].listeners[].here.state string    
realms[].listeners[].here.why string, or null    
realms[].listeners[].hostnames list    
realms[].listeners[].hostnames[] string    
realms[].listeners[].id string    
realms[].listeners[].port integer    
realms[].listeners[].publicBaseUrl string, or null    
realms[].name string    
realms[].pathPrefix string    
realms[].retiring object    
realms[].retiring.finish string    
realms[].retiring.finishesBy number    
realms[].retiring.inProgress boolean    
realms[].retiring.interrupted boolean    
realms[].retiring.refusing string    
realms[].retiring.since number    
realms[].retiring.sinceIso string    
realms[].retiring.why string    
realms[].settings list    
realms[].settings[].group string    
realms[].settings[].key string    
realms[].settings[].label string    
realms[].settings[].value string    
reserved list    
reserved[] string    
settings object   The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns.
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer   How many of them can be changed while the service runs.
settings.groups list   In the order config.js declares them.
settings.groups[] object   One group’s settings.
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[] object   One setting: what it is, what it is set to, and where that came from.
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   Present beside csvValues where the setting describes each value: the value mapped to one sentence.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list   Present on a csv setting whose entries must each be one of these; absent on an open list.
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean    
settings.groups[].settings[].description string   What it does and why the default is the default.
settings.groups[].settings[].editRefusal string   Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer.
settings.groups[].settings[].editable boolean   Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked.
settings.groups[].settings[].enumValues list   Present on enum settings only.
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string   Its environment variable.
settings.groups[].settings[].group string   The protocol it belongs to, and the console’s section heading.
settings.groups[].settings[].key string   The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize.
settings.groups[].settings[].label string    
settings.groups[].settings[].masked boolean   Present, true, when a sensitive value here was replaced.
settings.groups[].settings[].max number   The highest value it will take.
settings.groups[].settings[].min number   The lowest value POST /config/set will take, on an int setting that declares one.
settings.groups[].settings[].ordered boolean   Present, true, on a csv setting whose order is a preference: the first value is the most preferred.
settings.groups[].settings[].overridden boolean   Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string.
settings.groups[].settings[].realmSettable boolean   Whether a trust realm may hold its own value for it.
settings.groups[].settings[].restartReason string   Why it is not editable, when the value was consumed at startup.
settings.groups[].settings[].selectAll object   Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on.
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source one of realm, override, env, env-legacy, appconfig, defaults, default   Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is reachable only for the DERIVED settings, whose value is a function of a neighbouring setting: for every other setting, no value anywhere stops this service from STARTING.
settings.groups[].settings[].step number   The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30.
settings.groups[].settings[].text string   The same value on one line: what the console shows in its input and what the environment variable would carry.
settings.groups[].settings[].type string   How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color).
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean    
settings.overridden list   The keys on this page with a runtime override in force.
settings.overridden[] string    
settings.page string    
settings.setWith string   The operation that writes them.
settings.settingCount integer    
settings.sharedWith map   A group drawn on another page as well, and those pages.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string, or null    
settings.sharedWith.{key}[].path string    
support list    
support[].by string    
support[].cards list    
support[].cards[] string    
support[].family string    
support[].note string    
support[].state string    

POST /admin-api/realms/create

createRealm

Define a trust realm

Every HTTP endpoint this service has begins answering under the new realm’s prefix immediately, with a signing key of its own and nothing issued yet.

The id becomes a PATH SEGMENT, so it is lower-case letters, digits and hyphens, starts with a letter or a digit, and is at most 31 characters. It may not be default, and it may not be the first segment of a path this service already serves — GET /admin-api/realms lists those in reserved.

The domain is the realm’s DNS domain — iyasec.io — and it is FIXED from here on. Its directory is a tree of its own at the RFC 2247 mapping of it (dc=iyasec,dc=io), no two realms may share one, and one inside another realm’s is allowed and is a separate tree. Omitted, it is <id>.<global.domain>.

EIGHT SETTINGS ARE SEEDED ON A NEW REALM FROM ITS DOMAIN and they are the ones that are NAMES rather than behaviour: the SAML 2.0 entityID (urn:<domain>:idp), the SAML 1.1 providerID (urn:<domain>:idp:saml11), the WS-Federation entityID, the WS-Trust issuer and the SAML assertion issuer (urn:<domain>:sts), the SPIFFE trust domain (the domain), the Kerberos realm (the domain in capitals), and the OpenID4VP verifier client id (the process’s with the id appended). Two realms carrying one entityID is not a configuration choice — it is two identity providers claiming one name, which a service provider is entitled to refuse. They are ORDINARY settings on the realm: pass overrides to choose your own, or unset them afterwards to go back to sharing the process’s name, which is a case worth being able to build for testing.

The OAuth issuer is deliberately NOT seeded: it defaults to naming the base URL a request arrived on, and that already carries the realm prefix.

Creation is capped by realms.maxCount, which counts the default realm. At the cap the create is refused and nothing is defined. Lowering the cap does not remove realms that already exist. Only a service administrator in the default realm may change the limit.

Mirrors POST /admin/realms 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
description string    
domain string   The realm’s DNS domain, at least two labels. Fixed once the realm exists; defaults to <id>.<global.domain>.
id string yes Lower-case letters, digits and hyphens. It is the path segment.
name string   What a person calls it. Free text; defaults to the id.
overrides object   Settings to set on the realm, named by the dot paths GET /admin-api/config lists. They win over the seeded names. Every realms.* key is refused on a realm: one of them decides whether realms exist and where they are found, and a realm carrying it would be changing how it was reached half way through the request that found it.

200: The realm id, in realm.

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

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

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

POST /admin-api/realms/remove

removeRealm

Remove a realm, and everything it holds

EVERYTHING IT ACCUMULATED GOES WITH IT: its sessions, its authorization codes, its tokens, its refresh families, its credential offers, its service providers, its statistics, its audit log and its signing key. That is deliberate rather than thorough — a realm re-created with the same id inheriting the last one’s sessions and tokens would be the single most surprising thing a re-created realm could do.

NOTHING IS REMOVED FROM THE DIRECTORY, because nothing there belongs to a realm: ou=users, ou=groups and ou=applications are shared by every realm in this process.

A realm cannot remove ITSELF — a call to /realm/acme/admin-api/realms/remove naming acme is refused. Everything about the removal would work; what would not is the caller, which would be talking to a prefix that had stopped existing. Call it from another realm, or from the default one.

The DEFAULT realm cannot be removed at all.

Mirrors POST /admin/realms 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  

200: The realm id, in realm.

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

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

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

POST /admin-api/realms/set

setRealmSetting

Set one setting on one realm

The value applies to the next request that arrives under that realm’s prefix and to nothing else — above whatever the process as a whole is configured with, and below nothing.

This is the same store POST /realm/<id>/admin-api/config/set writes to, and either is fine; the difference is only which realm you have to be in to make the call. A setting whose editable is false is refused with the reason, exactly as it is on the service-wide resource, and every realms.* key is refused outright. realms.maxCount is process-wide; only the default realm’s service administrator changes it, and a create past that limit is refused. Lowering the limit does not remove realms.

Mirrors POST /admin/realms 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  
key string yes  
value any JSON yes  

200: The realm and the key, in realm and key.

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

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

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

POST /admin-api/realms/unset

unsetRealmSetting

Drop one setting from one realm

The realm falls back to whatever this service as a whole is configured with — which may itself be a runtime override, and is left alone. A key the realm does not set is refused rather than treated as already done, because the two are different facts and a caller that misspelt a key would otherwise be told it succeeded.

Mirrors POST /admin/realms 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  
key string yes  

200: The realm and the key, in realm and key.

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

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

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

POST /admin-api/realms/update

updateRealm

Rename a realm, or describe it

The id cannot be changed, because it is the path segment every client was given. Define a new realm and remove this one if that is what is wanted — and note that the new one gets a new signing key, which is the honest consequence of it being a different realm. The domain is fixed for the same kind of reason: a domain other than the realm’s own is refused (STS-CORE-0101), and the same value again is accepted and changes nothing.

Mirrors POST /admin/realms 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
description string    
domain string    
id string yes  
name string    

200: The realm id, in realm.

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string    

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

Member Type Required What it is
bootstrap object    
bootstrap.created boolean    
bootstrap.passwordResetRequired boolean    
bootstrap.username string    
error string    
error_description string    
errors list    
errors[] string    
key string    
message string    
ok boolean yes  
password string   The bootstrap administrator’s generated password, in product mode, once.
prefix string    
realm string    
retirement object    
retirement.boundSeconds number    
retirement.failed list    
retirement.failed[] string    
retirement.late list    
retirement.late[] string    
retirement.undelivered list    
retirement.undelivered[].count number    
retirement.undelivered[].what string    
retiring object    
retiring.finish string    
retiring.finishesBy number    
retiring.inProgress boolean    
retiring.interrupted boolean    
retiring.refusing string    
retiring.since number    
retiring.sinceIso string    
retiring.why string    
username string