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 |