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.
| Operation | Method and path | Who may call it |
|---|---|---|
| Get multi-factor status | GET /api/me/mfa | console session |
| Start authenticator set-up | POST /api/me/mfa/enrol | console session |
| Confirm authenticator set-up | POST /api/me/mfa/confirm | console session |
| Turn off the authenticator | POST /api/me/mfa/disable | console session |
| Replace recovery codes | POST /api/me/mfa/recovery-codes | console 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | The account already has a passkey and this session has not passed a second-factor check in the last 15 minutes. |
| 409 | mfa_enrolled | An 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)
| Field | Type | Required | Description |
|---|---|---|---|
code | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | The account already has a passkey and this session has not passed a second-factor check in the last 15 minutes. |
| 400 | mfa_not_pending | Set-up was not started, or an authenticator app is already confirmed. |
| 400 | mfa_invalid | The code is wrong, malformed or was already used. |
| 429 | mfa_locked | Five 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)
| Field | Type | Required | Description |
|---|---|---|---|
code | string | yes | A current 6-digit authenticator code, or an unused recovery code. |
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | mfa_not_enrolled | No authenticator app is confirmed on the account. |
| 400 | mfa_invalid | The code is wrong, malformed or was already used. |
| 429 | mfa_locked | Five 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)
| Field | Type | Required | Description |
|---|---|---|---|
code | string | yes | A 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
| Status | Code | When |
|---|---|---|
| 400 | mfa_not_enrolled | No authenticator app is confirmed on the account. |
| 400 | mfa_invalid | The code is wrong, malformed or was already used. |
| 429 | mfa_locked | Five 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.
| Field | Type | Always present | Description |
|---|---|---|---|
enrolled | boolean | yes | True when a confirmed authenticator app is on the account. Passkeys are counted separately, in passkeys. |
confirmedAt | string or null | yes | When the authenticator app was confirmed. Null when there is none, or when set-up was started and not finished. |
recoveryCodesLeft | integer | yes | How many unused recovery codes remain. 0 when no authenticator app is confirmed. |
verifiedAt | string or null | yes | When 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. |
passkeys | integer | yes | How 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.
| Field | Type | Always present | Description |
|---|---|---|---|
secret | string | yes | The authenticator secret in base32, for typing in by hand. It is shown only in this answer. |
otpauthUri | string | yes | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
recoveryCodes | array of string | yes | Ten single-use codes that stand in for an authenticator code. They are shown only in this answer; only their hashes are kept. |
Nullgap documentation