This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
What happened here, in order — history rather than state, and read-only. It carries no credential of any kind and has no clear operation: an erase control on an administrative surface would make an audit log unable to answer the one question it exists for.
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/audit
getAudit
What happened here, in order, filtered and paged
Every authentication, session, LDAP directory operation, console interaction, management API call and protocol endpoint call, newest first.
This is HISTORY where the rest of this API is STATE. /admin-api/metrics can say the directory holds eleven entries; only this can say a twelfth was created at 14:02 and deleted at 14:03 by somebody bound as uid=carol, over LDAPS.
NO CREDENTIAL IS EVER IN A ROW. Not a password, not a bearer token, not an assertion, and no request or response body. A modify names the attributes it changed and never their values, because a modify is where a userPassword gets set; a compare says whether it matched and not what was tried; an authorization code in a query string is replaced with (redacted).
One act usually produces several events. A sign-in writes three — the HTTP call, the credential being accepted, and the session that came out of it. They are three facts at three layers, and a Kerberos AS-REQ authenticates somebody and starts no session at all.
RESUME BY at, not by page. Every event has a seq that is unique across every process of the service and never reused, including across a drop and a restart, and that rises within each process (#465). It is NOT one order across processes — request workers and cluster nodes each number from blocks of their own — so read what is new by at, with seq (and origin) as the tie-break and as the event’s name.
Mirrors GET /admin/audit on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
category |
query | one of authentication, session, directory, admin, api, application, protocol, spiffe, signals, authorization, service, mail |
One of the categories. The reply’s categories member describes each of them. |
|
action |
query | one of authentication, authentication.refused, portal.activate, portal.activate.refused, portal.password.changed, authn.password.changed, portal.password.refused, portal.password.csrf, portal.signout, portal.signout.csrf, portal.key.enrolled, portal.key.removed, portal.key.renamed, portal.tls-client.issued, portal.tls-client.revoked, activation.issued, portal.password-reset, portal.password-reset.refused, authn.mfa.enrolment.required, authn.mfa.enrolment.started, authn.mfa.enrolment.offered, authn.mfa.enrolment.declined, authn.second-factor.skipped, authn.mfa.enrolment.at-risk, authn.mfa.enrolled, authn.recovery.refused, authn.recovery.limited, authn.recovery.completed, authn.sign-in.started-over, portal.mfa.started, portal.mfa.enrolled, portal.mfa.refused, portal.mfa.removed, portal.mfa.csrf, portal.activate.mfa.started, portal.activate.mfa.refused, portal.activate.key.started, portal.activate.key.enrolled, portal.activate.key.refused, session.start, session.end, session.renew, authn.session.bound, authn.session.refreshed, authn.session.binding-skipped, logout.global, logout.selective, logout.backchannel, mail.queued, mail.sent, mail.dead, mail.refused, mail.reset-requested, mail.retry, mail.template, branding.logo, mail.verified, mail.preferences, scheduler.run, scheduler.step-down, keys.rotate, keys.rotate.emergency, application.secret-expiring, application.secret-expired, keys.retire, keys.data-key-rotate, keys.data-key-reencrypt, keys.data-key-destroy, keys.kek-rotate, keys.pin, keys.unpin, oidfed.key-minted, oidfed.key-rotated, oidfed.key-revoked, oidfed.subordinate-set, oidfed.subordinate-removed, oidfed.anchor-set, oidfed.anchor-removed, oidfed.mark-type-set, oidfed.remove-mark-type, oidfed.mark-policy-set, oidfed.remove-mark-policy, oidfed.mark-issued, oidfed.mark-revoked, oidfed.held-mark-added, oidfed.held-mark-removed, oidfed.act-refused, oidfed.resolved, device.create, device.browser.remembered, device.update, device.delete, device.evict, device.attestation-revoked, webauthn.ceremony, webauthn.algorithm-mismatch, webauthn.client.learned, webauthn.attestation-revoked, device.key-add, device.key-remove, device.compliance, device.enrol.refused, user.create, user.delete, user.update, user.rename, cells.rehome, user.query, group.create, group.delete, group.update, group.rename, entry.create, entry.delete, entry.update, entry.rename, directory.search, directory.compare, directory.bind, application.create, application.secret-revealed, application.export, application.import, application.add-owner, application.remove-owner, application.update, consent.grant, consent.deny, consent.revoke, application.delete, oidfed.registered, oidfed.registration-refused, admin.view, admin.change, admin.config-dump, claims.change, admin.role.change, admin.console.bootstrap, admin.mail.set, admin.pseudonym.set, admin.mfa.totp.cleared, admin.mfa.key.cleared, admin.mfa.key.renamed, admin.password.reset, admin.password.reset-link, admin.mfa.primary-keys.removed, admin.mfa.disabled, admin.mfa.required, admin.mfa.unrequired, admin.delegation.not-delegated, admin.delegation.may-act, admin.delegation.semantics, portal.delegation.may-act, portal.delegation.search, admin.password-policy.change, admin.authn-policy.change, admin.locale-policy.change, admin.post-login-policy.change, authn.post-login.asked, authn.post-login.skipped, authn.post-login.done, authn.post-login.held, admin.post-login-activity.change, authn.post-login.activity-run, authn.post-login.unsupported, webauthn.key.possibly-replaced, authn.mail-factor.change, authn.mail-factor.sent, authn.mail-factor.accepted, authn.mail-factor.refused, admin.truststore.change, admin.pki.trust.change, krb5.keys.derived, krb5.trust.sid-filtered, admin.krb5.keys.cleared, admin.krb5.service.created, admin.krb5.service.rotated, admin.krb5.service.deleted, admin.krb5.previous.dropped, api.read, api.change, protocol.call, oauth.token.revoke, protocol.failure, service.failure, spiffe.svid.issue, spiffe.svid.validate, spiffe.entry.create, spiffe.entry.update, spiffe.entry.delete, spiffe.agent.create, spiffe.agent.attest, spiffe.agent.ban, spiffe.agent.unban, spiffe.agent.delete, spiffe.bundle.read, spiffe.bundle.change, spiffe.call.refuse, xacml.decision, xacml.enforcement, authzen.decision, authzen.search, fga.decision, admin.authzen.attribute.set, admin.authzen.attribute.removed, admin.authzen.scope.set, admin.authzen.pep.granted, admin.authzen.callbacks.set, authzen.access-request.submitted, authzen.access-request.approved, authzen.access-request.denied, authzen.access-request.expired, authzen.access-request.cancelled, authzen.access-request.revoked, authzen.access-request.approver-refused, authzen.access-request.callback, xacml.issuance.refused, xacml.access.refused, xacml.issuance.alarm, xacml.pep.register, xacml.pep.certificate, xacml.pip.query, saml2.request.signature, gnap.grant.request, gnap.grant.consent, gnap.grant.deny, gnap.grant.approve, gnap.grant.revoke, gnap.grant.owner-queued, gnap.grant.forward, uma.resource.register, uma.resource.update, uma.resource.delete, uma.permission.ticket, uma.decision, uma.grant, uma.pct.revoke, uma.approval.request, uma.approval.answer, uma.claims.gathered, uma.share.add, uma.share.remove, uma.policy.alfa, uma.resource-server.enable, uma.resource-server.disable, uma.owns-resources.set, uma.rpt.revoke, gnap.grant.finalize, gnap.token.issue, gnap.token.rotate, gnap.token.revoke, gnap.rs.introspect, gnap.rs.register, ssf.stream.create, ssf.stream.update, ssf.stream.delete, ssf.stream.status, ssf.subject.change, ssf.event.transmit, ssf.announcement.broadcast, ssf.event.refused, ssf.stream.dead, ssf.stream.revived, ssf.stream.delivery, ssf.deadletter.clear, ssf.event.receive, caep.event.auto, caep.event.emit, caep.session.reset, caep.session.clear, risc.event.auto, risc.event.emit, risc.account.reset, risc.account.clear, persistence.minted-drop, admin.aud-sub.set, admin.mfa.backup-codes.cleared, admin.password.reset-keytab, admin.user.attribute, admin.service-account.set, admin.service-account.cleared, admin.service-account.owner-added, admin.service-account.owner-removed, admin.service-account.destination-set, admin.service-account.rotate, admin.app-password.created, admin.app-password.revoked, admin.ciba.answered, admin.device.removed, admin.ida.recorded, admin.ida.removed, admin.siop.enrolled, admin.siop.removed, admin.siop.preferred, admin.passkey.enrolment-started, admin.passkey.enrolment-refused, admin.passkey.enrolled, admin.passkey.upgrade-started, admin.passkey.upgrade-refused, admin.passkey.upgrade-proved, admin.passkey.upgrade-cancelled, admin.passkey.upgraded, ssf.signals.discover, ssf.signals.stream, ssf.signals.unblock, ssf.signals.read-stream, ssf.signals.update-stream, ssf.signals.delete-stream, ssf.signals.set-status, ssf.signals.add-subject, ssf.signals.remove-subject, ssf.signals.verify, application.key-issued, enrollment.acme.account.create, enrollment.acme.account.deactivate, enrollment.acme.account.key-change, enrollment.eab.create, enrollment.eab.delete, enrollment.challenge.create, enrollment.challenge.delete, enrollment.issue, enrollment.issue.refused, enrollment.revoke, federation.signal-block, federation.signal-unblock, federation.signout, federation.signout-answered, federation.unlink, federation.connected, federation.provider-notification, federation.group-ignored, group.add-member, group.add-owner, group.remove-owner, group.owner-protected, group.set-mail, group.set-policy, krb5.keytab.person, logout.backchannel.retry, oauth.device-secret.revoke, oauth2.ciba.notify, oauth2.claim-source-linked, oauth2.claim-source-link-refused, oauth2.claims-providers.add-provider, oauth2.claims-providers.update-provider, oauth2.claims-providers.remove-provider, oauth2.claims-providers.revoke-link, oauth2.command, oauth2.command.tenant, oauth2.grant-revoked, oauth2.par.withdraw, password.set, service-account.rotated, service-account.rotation-failed, portal.app-password.created, portal.app-password.revoked, portal.app-password.csrf, portal.certificates.csrf, portal.device.remove, portal.device.remember-browser, portal.kerberos.keytab, portal.kerberos.refused, portal.kerberos.csrf, portal.key.started, portal.key.refused, portal.key.upgrade-started, portal.key.upgrade-refused, portal.key.upgraded, portal.mfa.backup-codes.generated, portal.mfa.backup-codes.confirmed, portal.mfa.backup-codes.discarded, portal.risc.optOutInitiated, portal.risc.optOutCancelled, portal.risc.optIn, portal.signing-key.issued, portal.signing-key.removed, portal.signing-key.csrf, portal.signing-key.revoked, did.person.published, did.person.version, did.person.authorized, did.person.deactivated, admin.did.deactivated, portal.siop.enrol, portal.siop.remove, portal.siop.prefer, portal.siop.view, portal.siop.did, siop.key.pinned, siop.key.refused, portal.vc.offer, portal.vc.remove, risk.feedback, risk.response, risk.terms.accept, attribute-sources.add, attribute-sources.update, attribute-sources.remove, attribute-sources.refresh, scim-client.change, scim-client.delivery, scim-client.reconcile, scim-client.queue, secret-destination.push, secret-destination.test-push, roles.add-owner, roles.remove-owner, roles.create, roles.delete, roles.describe, node-health.collect-garbage, saml2.authnrequest, saml2.artifact.resolve, saml2.attribute-query, saml2.metadata.mdq, saml2.metadata.refresh, account.add, account.select, account.switch, account.forget, account.ambiguous, session.reauthenticate, session.presented, session.refuse, session.refused, ssf.event.act, ssf.stream.swept, xacml.pep.enable, xacml.pep.disable, xacml.pep.forget, xacml.policy.write, xacml.policy.delete, report.definition.create, report.definition.update, report.definition.share, report.definition.delete, report.job.submit, report.job.start, report.job.complete, report.job.fail, report.job.cancel, report.notify, report.query, report.job.retrieve, admin.audit-export.add, admin.audit-export.update, admin.audit-export.remove, admin.audit-export.enable, admin.audit-export.disable, admin.audit-export.test, audit.export.test |
One action. ANDed with category, so an action from another category matches nothing — which is what an empty list then means. The reply’s actions member lists every action with the category it belongs to. |
|
outcome |
query | one of success, refused, error |
Three rather than two on purpose: a refused is this service working correctly and saying no, an error is this service failing, and collapsing them would bury the one row worth paging somebody about under the fifty that are a client getting its parameters wrong. |
|
actor |
query | string | Substring of either spelling of the actor, case-insensitive — the normalised key (alice) or the form it was presented in (a bind DN, alice@REALM, an X.509 subject). A substring because the collapse to one key can only be done where an identity is normalised, and a directory row’s actor is a DN. |
|
q |
query | string | Substring of the summary, the target or the action, case-insensitive. | |
code |
query | string | The FRONT of an error code: a whole code is one failure condition and STS-OAUTH every failure in that subsystem. docs/error-codes.md lists them. Every refused or failed request carries a code; no code is ever sent to the client that made the request. |
|
address |
query | string | The FRONT of the client’s IP address, case-insensitive: a whole address is one client and 10.0. every client in that range. A prefix rather than a substring, so 10.0.0.1 cannot match inside 110.0.0.12. |
|
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 matching events, with the paging that found them and the vocabulary the filters take.
| Member | Type | Required | What it is |
|---|---|---|---|
actions |
list | ||
actions[].action |
string | ||
actions[].category |
string | ||
actions[].label |
string | ||
byAction |
map | ||
byAction.{key} |
number | ||
byCategory |
map | ||
byCategory.{key} |
number | ||
byOutcome |
map | ||
byOutcome.{key} |
number | ||
categories |
list | ||
categories[].category |
string | ||
categories[].label |
string | ||
categories[].what |
string | ||
dropped |
integer | Events discarded to stay under the cap. | |
events |
list | ||
events[].action |
string | ||
events[].actor |
string | ||
events[].actorForm |
string | ||
events[].address |
string | ||
events[].at |
number | ||
events[].category |
string | ||
events[].channel |
string | ||
events[].detail |
any JSON | What this one kind of event recorded about its own act: several hundred call sites each name their members, and values are trimmed by detailOf(). What this one kind of event recorded about its own act: several hundred call sites each name their members, and values are trimmed by detailOf(). |
|
events[].errorCode |
string, or null | ||
events[].mac |
string | ||
events[].origin |
string, or null | ||
events[].outcome |
string | ||
events[].prev |
string | ||
events[].protocol |
string | ||
events[].seq |
number | ||
events[].summary |
string | ||
events[].target |
string | ||
filter |
object | ||
filter.action |
string, or null | ||
filter.actor |
string, or null | ||
filter.address |
string, or null | ||
filter.category |
string, or null | ||
filter.code |
string, or null | ||
filter.outcome |
string, or null | ||
filter.q |
string, or null | ||
firstRow |
integer | ||
held |
integer | Events currently in the log. | |
knownActors |
map | The actors on this page that are people known here. | |
knownActors.{key} |
boolean | ||
lastRow |
integer | ||
matched |
integer | ||
maxEvents |
number | The cap: audit.maxEvents. |
|
newestSeq |
number | ||
oldestSeq |
number | ||
outcomes |
list | ||
outcomes[] |
string | ||
page |
integer | ||
pages |
integer | ||
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 | ||
perPage |
integer | ||
persisted |
boolean | ||
protocolCalls |
boolean | Whether ordinary protocol endpoint calls are being recorded. | |
recorded |
integer | Events recorded since this process started. | |
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 | ||
shown |
integer | ||
verifiesCredentials |
boolean |
400: The answer.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean |
GET /admin-api/audit/integrity
getAuditIntegrity
Check the held audit rows against their checksums
Each row carries a keyed checksum whose key is not in the database, and the checksum of the row its process wrote before it. altered lists the seq of any row that no longer matches. missing lists each place a row is gone from between two held rows of one process. head says whether this process’s newest row is still there: intact; truncated when its newest rows were removed; altered when the record of which row is newest was changed; none when it has written no signed row. The oldest rows leave by design at audit.maxEvents. unsigned counts rows written with no key-encryption key in the process.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
200: The result.
| Member | Type | Required | What it is |
|---|---|---|---|
altered |
list | yes | |
altered[] |
integer | ||
checked |
integer | yes | |
head |
one of intact, truncated, altered, none |
yes | |
missing |
list | yes | |
missing[].after |
integer | yes | |
missing[].before |
integer | yes | |
missing[].origin |
string | yes | |
unsigned |
integer | yes |
GET /admin-api/error-codes
getErrorCodes
Every failure condition this service can produce, and how often each is on the held audit log
The central table of error codes, STS-<SUBSYSTEM>-<NNNN>, filtered and paged: each code with the subsystem it belongs to, what failed, and what the CLIENT is told in its protocol’s own vocabulary (spec).
A CODE IS NEVER SENT TO A CLIENT. It is recorded on the audit row (errorCode on GET /admin-api/audit, filterable there with ?code=) and at the front of the service log line; every protocol response is exactly what it was.
seen counts the rows the audit log holds IN THIS REALM right now, so it falls as the log’s cap discards the oldest, and it is zero for a failure recorded only as a log line — a startup refusal, or anything the remote PEP container records. unregisteredSeen lists codes found on held rows that the table does not hold, each a failure site whose code was never registered.
The same table is published as docs/error-codes.md, generated from common/error_codes.js.
Mirrors GET /admin/error-codes on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
subsystem |
query | string | One subsystem id — OAUTH, LDAP, XPEP — as subsystems[].id lists them. Case-insensitive. |
|
q |
query | string | Substring of the code, the summary or what the client sees, case-insensitive — a code pasted out of a log line, or a protocol error name such as invalid_grant. |
|
seen |
query | string | 1 for only the codes on at least one held audit row. |
|
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 matching codes, the subsystems with their counts, and the paging that found them.
| Member | Type | Required | What it is |
|---|---|---|---|
auditRowsHeld |
integer | ||
auditRowsWithCode |
integer | ||
codes |
list | ||
codes[].code |
string | ||
codes[].lastSeenAt |
number | ||
codes[].retired |
boolean | ||
codes[].seen |
integer | ||
codes[].spec |
string | ||
codes[].subsystem |
string | ||
codes[].summary |
string | ||
distinctCodesSeen |
integer | ||
documentation |
string | ||
filter |
object | ||
filter.q |
string, or null | ||
filter.seen |
boolean, or null | ||
filter.subsystem |
string, or null | ||
firstRow |
integer | ||
lastRow |
integer | ||
matched |
integer | ||
neverSentToClients |
boolean | ||
page |
integer | ||
pages |
integer | ||
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 | ||
perPage |
integer | ||
registered |
integer | ||
retired |
integer | ||
shown |
integer | ||
subsystemCount |
integer | ||
subsystems |
list | ||
subsystems[].codes |
integer | ||
subsystems[].id |
string | ||
subsystems[].label |
string | ||
subsystems[].prefix |
string | ||
subsystems[].seen |
integer | ||
subsystems[].what |
string | ||
subsystems[].where |
string | ||
unregisteredSeen |
list | ||
unregisteredSeen[].code |
string | ||
unregisteredSeen[].lastSeenAt |
number | ||
unregisteredSeen[].seen |
integer |