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

getMultiFactor

Who holds a second factor, and how RFC 6238 is configured here

One row per person — this realm’s directory people and everybody this service has SEEN, unioned — saying whether they hold a password, how many of their passkeys may sign them in on their own (primaryKeys) and may be a SECOND factor (mfaKeys), and whether an authenticator app is enrolled. A passkey has no role since #1135: both counts are of the same keys, by what the realm lets a key do, so each is every key the person holds or none.

TWO MECHANISMS COUNT AS A SECOND FACTOR HERE: any passkey, where the realm lets one be a second factor, and an RFC 6238 authenticator app. A person holding either is asked for it at the sign-in screen and a password alone will not sign them in; secondFactor says which one they will be asked for, and somebody holding both is asked for the key with the code offered as the alternative.

totpUsable: false IS THE ROW TO LOOK FOR. It means an enrolment exists that this process cannot read — almost always a shared secret sealed under a key-encryption key that has since been rotated. Those people are REFUSED at the code step rather than let through on one factor, so they cannot sign in at all until the enrolment is cleared.

CODES ARE VERIFIED FOR REAL IN BOTH MODES, which almost nothing else in this service is. totp carries the algorithm table, read from the module that performs the algorithm.

The scan stops at 5,000 people (capped), because reading a credential per person happens on the one thread that answers every socket this service holds — the scan, not the count: counts is over the capped roster, and directoryPeople and directoryCounts over every person the directory defines, as on GET /admin-api/users (#610).

Mirrors GET /admin/users on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of the person’s name, case-insensitive.
factor query one of any, totp, key, none, unreadable   any is anybody holding a second factor of either kind; none is the complement of it; unreadable is a factor whose sealed secret this service can no longer open.
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 roster, the counts, and the RFC 6238 settings.

Member Type Required What it is
capped boolean    
counts object    
counts.noCredential number    
counts.passwordOnly number    
counts.people number    
counts.primaryKeys number    
counts.unreadable number    
counts.withKeys number    
counts.withSecond number    
counts.withTotp number    
directoryCountedAt string, or null    
directoryCounts object    
directoryCounts.neverSignedInHere number, or null    
directoryCounts.noWayIn number    
directoryCounts.passwordOnly number    
directoryCounts.people number    
directoryCounts.primaryKeys number    
directoryCounts.signedInHere number, or null    
directoryCounts.unreadable number    
directoryCounts.withKeys number    
directoryCounts.withPassword number    
directoryCounts.withSecond number    
directoryCounts.withTotp number    
directoryCountsKeptFor number, or null    
directoryPeople number, or null    
filter object    
filter.factor string, or null    
filter.kind string, or null    
filter.protocol string, or null    
filter.q string, or null    
firstRow integer    
lastRow integer    
matched number    
offered boolean    
page integer    
pages integer    
people list    
people[].backupCodes object    
people[].backupCodes.generatedAt number    
people[].backupCodes.hashed boolean    
people[].backupCodes.lastUsedAt number    
people[].backupCodes.legacy boolean    
people[].backupCodes.present boolean    
people[].backupCodes.remaining number    
people[].backupCodes.sealed boolean    
people[].backupCodes.total number    
people[].backupCodes.usable boolean    
people[].backupCodes.used number    
people[].backupCodes.why string    
people[].inDirectory boolean    
people[].known boolean    
people[].mfaKeys number    
people[].mfaRequired boolean    
people[].password boolean    
people[].primaryKeys number    
people[].recoveryAdvised boolean    
people[].secondFactor string, or null    
people[].totp boolean    
people[].totpDetail object    
people[].totpDetail.algorithm string    
people[].totpDetail.digits number    
people[].totpDetail.enrolledAt number    
people[].totpDetail.lastUsedAt number    
people[].totpDetail.period number    
people[].totpDetail.sealed boolean    
people[].totpDetail.unusable boolean    
people[].totpDetail.why string    
people[].totpUsable boolean    
people[].usable boolean    
people[].username string    
perPage integer    
scanLimit number    
scanned number    
shown number    
store boolean    
totp object    
totp.algorithms list    
totp.algorithms[].id string    
totp.algorithms[].inUse boolean    
totp.algorithms[].name string    
totp.algorithms[].note string    
totp.digits number    
totp.encoding string    
totp.offered boolean    
totp.period number    
totp.secretBits number    
totp.truncation string    
totp.window number    
webauthn object    
webauthn.algorithms list    
webauthn.algorithms[].coseAlg number    
webauthn.algorithms[].insecure boolean    
webauthn.algorithms[].name string    
webauthn.algorithms[].notOfferedBecause string    
webauthn.algorithms[].offered boolean    
webauthn.algorithms[].postQuantum boolean    
webauthn.algorithms[].rank number    
webauthn.algorithmsSource string    
webauthn.attestation string    
webauthn.attestationAllowSafetynet boolean    
webauthn.attestationAllowedAaguids list    
webauthn.attestationAllowedAaguids[] string    
webauthn.attestationAndroidSoftwareKeys boolean    
webauthn.attestationDemandsTrust boolean    
webauthn.attestationFormats list    
webauthn.attestationFormats[] string    
webauthn.attestationMinCertificationLevel string    
webauthn.attestationPolicy string    
webauthn.attestationPolicyConfigured string    
webauthn.attestationRequireFips boolean    
webauthn.attestationTrustAnchors number    
webauthn.attestationVerified boolean    
webauthn.authenticatorAttachment string    
webauthn.clientDataHash string    
webauthn.credProps boolean    
webauthn.curves list    
webauthn.curves[].coseCurve number    
webauthn.curves[].name string    
webauthn.insecureAlgorithms boolean    
webauthn.lanes list    
webauthn.lanes[].algorithms list    
webauthn.lanes[].algorithms[] string    
webauthn.lanes[].lane string    
webauthn.maxKeysPerPerson number    
webauthn.mds object    
webauthn.mds.active boolean    
webauthn.mds.job string    
webauthn.mds.known boolean    
webauthn.mds.loadedAt number    
webauthn.mds.nextUpdateAt number    
webauthn.mds.rows number    
webauthn.mds.serial number    
webauthn.mds.stale boolean    
webauthn.mds.url string    
webauthn.mds.version string    
webauthn.mfaAllowed boolean    
webauthn.offered boolean    
webauthn.pqcAlongsideClassical boolean    
webauthn.pqcOnly boolean    
webauthn.primaryAllowed boolean    
webauthn.registrationMode string    
webauthn.residentKey string    
webauthn.rpId string    
webauthn.rpIdSource string    
webauthn.rpName string    
webauthn.signatureCounter string    
webauthn.timeoutMs number    
webauthn.upgradeAlgorithms list    
webauthn.upgradeAlgorithms[] string    
webauthn.upgradeMode string    
webauthn.userVerification string    
webauthn.userVerificationEnforced boolean    
webauthn.usernameless boolean    

400: The answer.

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

POST /admin-api/mfa/clear-email-factor

clearEmailFactor

Turn off somebody’s emailed second factor

The same switch as POST /admin-api/users/clear-email-factor (#64): clears the emailed code or link the person opted into. It cannot lock anybody out.

Mirrors POST /admin/users 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
evidence string   How the person’s identity was verified, in at least 8 characters. Product mode requires it, and it is recorded in the audit log.
user string   Accepted for username.
username string yes The name they sign in as.

200: Whether a factor was turned off. sessionsEnded counts the sessions the emailed second factor signed in, which were ended (#722); every other stays.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
removed boolean    
sessionsEnded number    

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  
removed boolean    
sessionsEnded number    

POST /admin-api/mfa/clear-key

clearSecurityKey

Remove one of somebody’s security keys

Goes through the same removeKey() the person’s own portal calls, which is what carries the refusal that matters: it will not remove the last way in. A person with no password whose only PRIMARY key this is would be locked out by an operator’s call, and an operator must not be able to do what the owner is stopped from doing.

The credential id is the base64url one on GET /admin-api/mfa’s rows and on /portal/keys.

Mirrors POST /admin/users 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
credentialId string yes base64url, as WebAuthn produced it.
evidence string   How the person’s identity was verified, in at least 8 characters. Product mode requires it, and it is recorded in the audit log.
user string   Accepted for username.
username string yes  

200: How many keys are left. sessionsEnded counts the sessions the key signed in, which were ended (#722); every other stays.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
remaining number    
sessionsEnded number    
username 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  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
remaining number    
sessionsEnded number    
username string    

POST /admin-api/mfa/clear-totp

clearAuthenticatorApp

Clear somebody’s authenticator app enrolment

THE ONLY WAY BACK FOR SOMEBODY WHO HAS LOST THEIR PHONE. The shared secret lives on that device and this service cannot reach it, and there is deliberately no self-service reset anywhere — a second factor anybody can remove is not a second factor.

It CANNOT lock anybody out: a one-time code is never a primary credential here, so clearing one drops the account to one factor rather than to none. The person sets a new one up at /portal/mfa.

Clearing an enrolment nobody holds answers 400 rather than 200, because unlike a role grant there is no idempotent reading of it that is useful: the caller asked to clear a specific thing and it was not there.

Mirrors POST /admin/users 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
evidence string   How the person’s identity was verified, in at least 8 characters. Product mode requires it, and it is recorded in the audit log.
user string   Accepted for username.
username string yes The name they sign in as.

200: Whose enrolment was cleared. sessionsEnded counts the sessions the app’s codes signed in, which were ended (#722); every other stays.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
remaining number    
sessionsEnded number    
username 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  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
remaining number    
sessionsEnded number    
username string