Nullgap.dev Docs

API reference

Multi-factor sign-in

The signed-in person’s authenticator app and recovery codes.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
Get multi-factor statusGET /api/me/mfaconsole session
Start authenticator set-upPOST /api/me/mfa/enrolconsole session
Confirm authenticator set-upPOST /api/me/mfa/confirmconsole session
Turn off the authenticatorPOST /api/me/mfa/disableconsole session
Replace recovery codesPOST /api/me/mfa/recovery-codesconsole session

#Get multi-factor status

GET /api/me/mfa

Says whether the signed-in person has an authenticator app and passkeys on their account, how many recovery codes are left, and when the current session last passed a second-factor check.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Answer (200, application/json)

A MfaStatus object.

{
  "enrolled": true,
  "confirmedAt": "2026-10-02T08:15:00.000Z",
  "recoveryCodesLeft": 8,
  "verifiedAt": "2026-11-16T09:12:00.000Z",
  "passkeys": 1
}

#Start authenticator set-up

POST /api/me/mfa/enrol

Creates a new authenticator secret for the signed-in person and returns it for their authenticator app. Nothing is switched on yet: confirm with a code from the app to finish. Calling it again before confirming replaces the pending secret. Takes no request body.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Answer (200, application/json)

A MfaEnrolment object.

{
  "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "otpauthUri": "otpauth://totp/Nullgap:dana%40acme.example?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Nullgap&algorithm=SHA1&digits=6&period=30"
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredThe account already has a passkey and this session has not passed a second-factor check in the last 15 minutes.
409mfa_enrolledAn authenticator app is already confirmed on the account. Turn it off first to set it up again.

#Confirm authenticator set-up

POST /api/me/mfa/confirm

Finishes set-up with a first code from the authenticator app and returns the recovery codes, which are shown only once. The current session becomes a verified one and gets a new session cookie; every other session of the person is signed out.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Request body (application/json)

FieldTypeRequiredDescription
codestringyesThe current 6-digit code from the authenticator app. A recovery code is not accepted here.

Answer (200, application/json)

A RecoveryCodes object.

{
  "recoveryCodes": [
    "k7m2q-x4n9p"
  ]
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredThe account already has a passkey and this session has not passed a second-factor check in the last 15 minutes.
400mfa_not_pendingSet-up was not started, or an authenticator app is already confirmed.
400mfa_invalidThe code is wrong, malformed or was already used.
429mfa_lockedFive wrong codes in a row locked the second factor for 15 minutes.

#Turn off the authenticator

POST /api/me/mfa/disable

Removes the authenticator app and its recovery codes from the signed-in person's account, after checking a code. Passkeys on the account are not touched. The session gets a new cookie and is no longer counted as verified.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Request body (application/json)

FieldTypeRequiredDescription
codestringyesA current 6-digit authenticator code, or an unused recovery code.

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
400mfa_not_enrolledNo authenticator app is confirmed on the account.
400mfa_invalidThe code is wrong, malformed or was already used.
429mfa_lockedFive wrong codes in a row locked the second factor for 15 minutes.

#Replace recovery codes

POST /api/me/mfa/recovery-codes

Checks a code, then replaces every recovery code with ten new ones. The old codes stop working at once. The new ones are shown only in this answer.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Request body (application/json)

FieldTypeRequiredDescription
codestringyesA current 6-digit authenticator code, or an unused recovery code.

Answer (200, application/json)

A RecoveryCodes object.

{
  "recoveryCodes": [
    "k7m2q-x4n9p"
  ]
}

Errors specific to this call

StatusCodeWhen
400mfa_not_enrolledNo authenticator app is confirmed on the account.
400mfa_invalidThe code is wrong, malformed or was already used.
429mfa_lockedFive wrong codes in a row locked the second factor for 15 minutes.

#Objects

The objects the operations above take and return.

#MfaStatus

The state of multi-factor sign-in on the signed-in person's account, and of the current session.

FieldTypeAlways presentDescription
enrolledbooleanyesTrue when a confirmed authenticator app is on the account. Passkeys are counted separately, in passkeys.
confirmedAtstring or nullyesWhen the authenticator app was confirmed. Null when there is none, or when set-up was started and not finished.
recoveryCodesLeftintegeryesHow many unused recovery codes remain. 0 when no authenticator app is confirmed.
verifiedAtstring or nullyesWhen this session last passed a second-factor check, by code or by passkey. Null if it never did. Sensitive actions ask for a check made in the last 15 minutes.
passkeysintegeryesHow many passkeys are on the account. Each one counts as a second factor.

#MfaEnrolment

What an authenticator app needs to be added to the account. Nothing is switched on until a code confirms it.

FieldTypeAlways presentDescription
secretstringyesThe authenticator secret in base32, for typing in by hand. It is shown only in this answer.
otpauthUristringyesThe same secret as an otpauth:// address, to show as a QR code. Codes are 6 digits and change every 30 seconds.

#RecoveryCodes

A fresh set of recovery codes.

FieldTypeAlways presentDescription
recoveryCodesarray of stringyesTen single-use codes that stand in for an authenticator code. They are shown only in this answer; only their hashes are kept.

Nullgap documentation