Multi-factor authentication

An account can use a TOTP authenticator app and WebAuthn credentials such as passkeys as a second factor, with one-use backup codes as a fallback. A registered passkey works for sudo mode and passwordless login right away, but password login only asks for it after Set WebAuthn two-factor authentication turns it on.

TOTP parameters

Fluxer accepts six-digit HMAC-SHA-1 codes with a 30-second time step and one step of clock skew either way. Your client generates the Base32 secret, shows it to the user and sends it with a code to Enable TOTP MFA.

Backup codes

An account gets 10 backup codes when it enables TOTP, and when it turns on passkeys as a second factor while it has no unused codes. Each code works once, and Fluxer ignores case, spaces and hyphens when it compares them. You can send a backup code wherever a TOTP code is accepted, except in Enable TOTP MFA. Fluxer deletes every code when the account is left with no second factor.

A user who lost their codes and their authenticator can get them back by email without sudo mode.

Start MFA backup codes challenge emails a code and returns a ticket that lasts 30 minutes.
Verify MFA backup codes challenge code trades the code, which lasts 10 minutes, for the current codes and a proof.
Regenerate MFA backup codes uses the proof to replace the set.

The account needs a verified email address and a second factor turned on. On an instance where people sign in with a username these routes return 400 EMAIL_UNAVAILABLE_ON_INSTANCE, and on an instance that sends no email they return 400 EMAIL_CODES_UNAVAILABLE. Ticket, code and proof errors come back as INVALID_FORM_BODY validation errors.

Each step also has a limit of its own, on top of its route bucket.

Step	Limit
Start	3 emails per 15 minutes for each account
Resend	3 emails per 15 minutes for each account, and 30 seconds between emails on a ticket
Verify	5 attempts per 15 minutes for each ticket
Regenerate	5 attempts per 15 minutes for each ticket

Sudo mode

Sudo mode is a recent proof that the account holder is present, and security-sensitive operations need it. Send the proof as sudo verification object fields in the JSON body, or send an earlier token in the X-Fluxer-Sudo-Mode-JWT header. After a TOTP, backup code, passkey or email code proof, Fluxer returns a token in the same response header, and it works for five minutes on any of the account's sessions. A password proof returns no token, and the account sends password on each call.

The first row that matches the account says which proofs it can send.

Account state	Proof to send
A second factor is turned on	`mfa_method` of `totp` or `webauthn` with its fields
Has a password	`password`, or `webauthn` with a passkey
Has a confirmed email address on an instance that sends email	`mfa_method` of `email_code` after Send a sudo email code, or `webauthn` with a passkey
Connected to SSO	Nothing, from a session that signed in with SSO in the last 10 minutes. Older sessions sign in with SSO again first
None of these	Nothing, and the operation goes ahead

Without a proof, the request returns 403 SUDO_MODE_REQUIRED with the sudo mode methods fields. A wrong password returns 400 INVALID_PASSWORD on the path password, and a wrong TOTP code, backup code or passkey assertion returns 400 INVALID_MFA_CODE on the path mfa_code. The totp method allows 10 attempts per 15 minutes for each account, and a correct code resets the count. A wrong email code returns 400 INVALID_SIGN_IN_CODE, a ticket past 10 minutes or 5 wrong tries returns 400 SIGN_IN_CODE_EXPIRED, and an unknown ticket returns 400 UNKNOWN_SIGN_IN_TICKET.

Sudo mode methods object

SUDO_MODE_REQUIRED responses have these fields at the top level of the error response.

Structure

Field	Type	Description
has_mfa	boolean	Whether the account has TOTP or at least one passkey
methods	sudo mode method availability object	The proofs the account can give

Sudo mode method availability object

Structure

Field	Type	Description
totp	boolean	Whether the account has TOTP enabled
webauthn	boolean	Whether the account has at least one passkey
backup_codes¹	boolean	Whether the account has at least one unused backup code
email_code?	boolean	Whether the account can prove sudo mode with an emailed code
password?	boolean	Whether the account can prove sudo mode with its password
sso_reauth	boolean	Whether the account proves sudo mode by signing in with SSO again. Always false while the instance has SSO turned off

¹ A backup code goes in mfa_code with mfa_method set to totp, also on an account without TOTP. There is no backup_codes method

Sudo MFA methods object

Structure

Field	Type	Description
totp	boolean	Whether the account has TOTP enabled
webauthn	boolean	Whether the account has at least one passkey
backup_codes	boolean	Whether the account has at least one unused backup code
has_mfa	boolean	Whether the account has TOTP or at least one passkey
email_code?	boolean	Whether the account can prove sudo mode with an emailed code
password?	boolean	Whether the account can prove sudo mode with its password

Sudo verification object

Operations that need sudo mode accept these fields in their JSON body.

Structure

Field	Type	Description
password?	string	Account password (8-256 characters)
mfa_method?	string	One of `totp`, `webauthn` or `email_code`
mfa_code?	string	TOTP code or unused backup code, for `totp` (1-32 characters)
webauthn_response?	WebAuthn assertion object	Assertion for `webauthn_challenge`, for `webauthn`
webauthn_challenge?	string	Challenge from Create sudo WebAuthn authentication options (1-256 characters)
email_code_ticket?	string	Ticket from Send a sudo email code, for `email_code` (1-128 characters)
email_code?	string	The 6-digit code from the email, for `email_code`

MFA backup codes object

Structure

Field	Type	Description
backup_codes	array[MFA backup code object]	The account's current backup codes

Example

{
  "backup_codes": [
    {"code": "a3f2-9kd7", "consumed": false},
    {"code": "b81c-4nq0", "consumed": true}
  ]
}

MFA backup code object

Structure

Field	Type	Description
code	string	The code, two groups of four lowercase letters and digits
consumed	boolean	Whether the code has been used

MFA backup codes challenge object

Structure

Field	Type	Description
ticket	string	The ticket to send in later steps
code_expires_at	ISO8601 timestamp	When the emailed code expires
resend_available_at	ISO8601 timestamp	When you can ask for another code

MFA backup codes verification object

Structure

Field	Type	Description
backup_codes	array[MFA backup code object]	The account's current backup codes
verification_proof	string	The proof for Regenerate MFA backup codes

WebAuthn credential object

An account can have up to 10 WebAuthn credentials.

Structure

Field	Type	Description
id	string	Base64url credential ID
name	string	Name the user gave the credential (1-100 characters)
created_at	ISO8601 timestamp	When the credential was registered
last_used_at	?ISO8601 timestamp	When the credential was last used, or null if never
rp_id	string	The domain the passkey was created for

WebAuthn credential descriptor object

Structure

Field	Type	Description
id	string	Base64url credential ID
type	string	Always `public-key`
transports?	array[string]	Transports the authenticator reported at registration, or `internal`, `hybrid`, `usb`, `nfc` and `ble` when it reported none

WebAuthn authenticator transports

Value	Description
ble	Bluetooth Low Energy
cable	Cloud-assisted Bluetooth Low Energy
hybrid	Hybrid transport
internal	Platform authenticator
nfc	Near-field communication
smart-card	Smart card
usb	USB authenticator

WebAuthn assertion object

The PublicKeyCredential JSON the browser WebAuthn API produces.

Structure

Field	Type	Description
id	string	Base64url credential ID
rawId	string	Base64url raw credential ID
response	WebAuthn assertion response object	Authenticator assertion response
authenticatorAttachment?	string	Either `cross-platform` or `platform`
clientExtensionResults	WebAuthn client extension results object	Client extension outputs
type	string	Always `public-key`

WebAuthn assertion response object

Structure

Field	Type	Description
clientDataJSON	string	Base64url client data JSON
authenticatorData	string	Base64url authenticator data
signature	string	Base64url assertion signature
userHandle?	string	Base64url user handle, for a discoverable credential

WebAuthn registration response object

Structure

Field	Type	Description
id	string	Base64url credential ID
rawId	string	Base64url raw credential ID
response	WebAuthn attestation response object	Authenticator attestation response
authenticatorAttachment?	string	Either `cross-platform` or `platform`
clientExtensionResults	WebAuthn client extension results object	Client extension outputs
type	string	Always `public-key`

WebAuthn attestation response object

Structure

Field	Type	Description
clientDataJSON	string	Base64url client data JSON
attestationObject	string	Base64url attestation object
authenticatorData?	string	Base64url authenticator data
transports?	array[string]	Transports the authenticator supports
publicKeyAlgorithm?	integer	COSE public key algorithm identifier
publicKey?	string	Base64url credential public key

WebAuthn client extension results object

Fluxer accepts extension result fields beyond these.

Structure

Field	Type	Description
appid?	boolean	Whether the AppID extension was used
credProps?	WebAuthn credential properties object	Credential properties output
hmacCreateSecret?	boolean	Whether the authenticator created an HMAC secret

WebAuthn credential properties object

Structure

Field	Type	Description
rk?	boolean	Whether the created credential is discoverable

WebAuthn authentication options object

The options to pass to navigator.credentials.get(), returned for sudo mode here and for login on HTTP authentication.

Structure

Field	Type	Description
challenge	string	Base64url one-use challenge, valid for five minutes
timeout	integer	Authenticator timeout in milliseconds, always `60000`
rpId	string	Relying party ID, the instance's `FLUXER_PASSKEY_RP_ID`
allowCredentials?	array[WebAuthn credential descriptor object]	The account's passkeys, left out for discoverable login
userVerification	string	One of `discouraged`, `preferred` or `required`

WebAuthn registration options object

The options to pass to navigator.credentials.create().

Structure

Field	Type	Description
rp	WebAuthn relying party object	Relying party identity
user	WebAuthn registration user object	The account the credential belongs to
challenge	string	Base64url one-use challenge, valid for five minutes
pubKeyCredParams	array[WebAuthn public key parameter object]	Accepted algorithms, COSE `-8`, `-7` and `-257`
timeout	integer	Authenticator timeout in milliseconds, always `60000`
excludeCredentials	array[WebAuthn credential descriptor object]	The account's existing credentials
authenticatorSelection	WebAuthn authenticator selection object	Authenticator requirements
attestation	string	Always `none`
extensions	WebAuthn client extension inputs object	Requested extensions, `credProps` only
hints	array[string]	Always empty

WebAuthn relying party object

Structure

Field	Type	Description
name	string	Relying party display name
id	string	Relying party ID, the instance's `FLUXER_PASSKEY_RP_ID`

WebAuthn registration user object

Structure

Field	Type	Description
id	string	User handle, the account snowflake as a decimal string in base64url
name	string	Account username
displayName	string	Account username

WebAuthn public key parameter object

Structure

Field	Type	Description
alg	integer	COSE algorithm identifier
type	string	Always `public-key`

WebAuthn authenticator selection object

Structure

Field	Type	Description
authenticatorAttachment?	string	Either `cross-platform` or `platform`
requireResidentKey?	boolean	Whether a discoverable credential is required
residentKey?	string	One of `discouraged`, `preferred` or `required`
userVerification?	string	One of `discouraged`, `preferred` or `required`

WebAuthn client extension inputs object

Structure

Field	Type	Description
appid?	string	AppID extension value
credProps?	boolean	Whether credential properties are requested
hmacCreateSecret?	boolean	Whether HMAC secret creation is requested
minPinLength?	boolean	Whether minimum PIN length is requested

Sudo email code object

Structure

Field	Type	Description
ticket	string	The value to send back as `email_code_ticket`
code_expires_at	ISO8601 timestamp	When the emailed code expires, 10 minutes after sending
resend_available_at	ISO8601 timestamp	When you can ask for another code, 30 seconds after sending

WebAuthn two-factor object

Structure

Field	Type	Description
user	user object	The updated account
backup_codes	?array[MFA backup code object]	The 10 new codes, or null when the call created none

Enable TOTP MFA

POST/v1/users/@me/mfa/totp/enable

MFA

Enables TOTP and returns 10 new backup codes. You need sudo mode and a verified account. Sends a User Update Gateway event.

JSON body

The body extends the sudo verification object with these fields.

Field	Type	Description
secret	string	Base32 TOTP secret your client generated (1-256 characters)
code	string	Current TOTP code for `secret`, not a backup code (1-32 characters)

Response

Status	Body	Condition
200	MFA backup codes object	TOTP was enabled
400	error response	`INVALID_CODE` on the path `code`, or `TWO_FA_ALREADY_ENABLED` when TOTP is already enabled
403	error response	`MFA_EMAIL_VERIFICATION_REQUIRED` or `ACCOUNT_VERIFICATION_REQUIRED` when the account isn't verified

The rate limit is 10 requests per minute, on the user:mfa:totp:enable bucket.

Disable TOTP MFA

POST/v1/users/@me/mfa/totp/disable

MFA

Disables TOTP under sudo mode and returns 204. This deletes every backup code unless passkeys stay on as a second factor. Sends a User Update Gateway event.

JSON body

The body extends the sudo verification object with this field.

Field	Type	Description
code¹	string	Current TOTP code or unused backup code (1-32 characters)

¹ Without a sudo token or mfa_method, code also proves sudo mode

Response

Status	Body	Condition
204	empty	TOTP was disabled
400	error response	`INVALID_CODE` on the path `code`, or `INVALID_MFA_CODE` on the path `mfa_code` when `code` proves sudo mode
400	error response	`TWO_FACTOR_REQUIRED` when TOTP isn't enabled

The rate limit is 10 requests per minute, on the user:mfa:totp:disable bucket.

List MFA backup codes

POST/v1/users/@me/mfa/backup-codes

MFA

Returns the account's backup codes, and replaces them with 10 new codes first when regenerate is true. You need sudo mode, and replacing the codes also needs a verified account.

JSON body

The body extends the sudo verification object with this field.

Field	Type	Description
regenerate	boolean	Whether to delete the current codes and create 10 new ones

Response

Status	Body	Condition
200	MFA backup codes object	The current or new codes were returned
403	error response	`MFA_EMAIL_VERIFICATION_REQUIRED` or `ACCOUNT_VERIFICATION_REQUIRED` when `regenerate` is true and the account isn't verified

The rate limit is 6 requests per minute, on the user:mfa:backup_codes bucket.

Start MFA backup codes challenge

POST/v1/users/@me/mfa/backup-codes/challenge

Emails a verification code to the account and returns a ticket. The body is empty or {}.

Response

Status	Body	Condition
200	MFA backup codes challenge object	The code was sent
400	error response	`TWO_FACTOR_REQUIRED` when the account has no second factor turned on
400	error response	`EMAIL_CODES_UNAVAILABLE` when the instance doesn't send email
403	error response	`MFA_EMAIL_VERIFICATION_REQUIRED` when the email address is unverified

The rate limit is 6 requests per minute, on the user:mfa:backup_codes_challenge:start bucket.

Resend MFA backup codes challenge code

POST/v1/users/@me/mfa/backup-codes/challenge/resend

Emails a new code for the ticket and returns 204. The old code and any proof already issued for the ticket stop working.

JSON body

Field	Type	Description
ticket	string	Ticket from Start MFA backup codes challenge (1-256 characters)

Response

Status	Body	Condition
204	empty	A new code was sent
400	error response	`INVALID_OR_EXPIRED_TICKET` when the ticket is unknown or expired

The rate limit is 6 requests per minute, on the user:mfa:backup_codes_challenge:resend bucket.

Verify MFA backup codes challenge code

POST/v1/users/@me/mfa/backup-codes/challenge/verify

Checks the emailed code and returns the account's backup codes and a proof. A code works once.

JSON body

Field	Type	Description
ticket	string	Ticket from Start MFA backup codes challenge (1-256 characters)
code	string	The code from the email (1-256 characters)

Response

Status	Body	Condition
200	MFA backup codes verification object	The code was accepted
400	error response	`INVALID_VERIFICATION_CODE`, `VERIFICATION_CODE_EXPIRED` or `VERIFICATION_CODE_NOT_ISSUED`

The rate limit is 20 requests per minute, on the user:mfa:backup_codes_challenge:verify bucket.

Regenerate MFA backup codes

POST/v1/users/@me/mfa/backup-codes/challenge/regenerate

Replaces the account's backup codes with 10 new ones. The ticket and proof can be used again until the ticket expires.

JSON body

Field	Type	Description
ticket	string	Ticket from Start MFA backup codes challenge (1-256 characters)
verification_proof	string	Proof from Verify MFA backup codes challenge code (1-256 characters)

Response

Status	Body	Condition
200	MFA backup codes object	The codes were replaced
400	error response	`INVALID_PROOF_TOKEN`, `INVALID_OR_EXPIRED_TICKET` or `TWO_FACTOR_REQUIRED`

The rate limit is 6 requests per minute, on the user:mfa:backup_codes_challenge:regenerate bucket.

List WebAuthn credentials

GET/v1/users/@me/mfa/webauthn/credentials

Returns the account's WebAuthn credentials.

Response

Status	Body	Condition
200	array[WebAuthn credential object]	The credentials were returned

The rate limit is 40 requests per 10 seconds, on the mfa:webauthn:list bucket.

Create WebAuthn registration options

POST/v1/users/@me/mfa/webauthn/credentials/registration-options

MFA

Returns a registration challenge for Register WebAuthn credential. You need sudo mode and a verified account or one that only needs a password, and the response never has a sudo token.

JSON body

The body is a sudo verification object.

Response

Status	Body	Condition
200	WebAuthn registration options object	The challenge was created
400	error response	`WEBAUTHN_CREDENTIAL_LIMIT_REACHED` when the account has 10 credentials
403	error response	`MFA_EMAIL_VERIFICATION_REQUIRED` when the account needs to confirm or add an email address to be verified

The rate limit is 20 requests per 10 seconds, on the mfa:webauthn:registration_options bucket.

Register WebAuthn credential

POST/v1/users/@me/mfa/webauthn/credentials

Adds a WebAuthn credential to the account and returns 204. A challenge works only once, even when registration fails, and you need new options to try again. Sends a WebAuthn Credentials Update Gateway event, and a User Update event for the account's first credential.

JSON body

Field	Type	Description
response	WebAuthn registration response object	The authenticator's response to the challenge
challenge	string	Challenge from Create WebAuthn registration options (1-1024 characters)
name	string	Name for the credential (1-100 characters)

Response

Status	Body	Condition
204	empty	The credential was registered
400	error response	`INVALID_WEBAUTHN_CREDENTIAL`, `INVALID_WEBAUTHN_PUBLIC_KEY_FORMAT` or `INVALID_WEBAUTHN_CREDENTIAL_COUNTER`
400	error response	`WEBAUTHN_CREDENTIAL_LIMIT_REACHED` when the account has 10 credentials
403	error response	`MFA_EMAIL_VERIFICATION_REQUIRED` when the account needs to confirm or add an email address to be verified

The rate limit is 10 requests per minute, on the mfa:webauthn:register bucket.

Rename WebAuthn credential

PATCH/v1/users/@me/mfa/webauthn/credentials/{credential_id}

MFA

Renames a WebAuthn credential under sudo mode and returns 204. Sends a WebAuthn Credentials Update Gateway event.

JSON body

The body extends the sudo verification object with this field.

Field	Type	Description
name	string	New name for the credential (1-100 characters)

Response

Status	Body	Condition
204	empty	The credential was renamed
404	error response	`UNKNOWN_WEBAUTHN_CREDENTIAL`

The rate limit is 20 requests per 10 seconds, on the mfa:webauthn:update bucket.

Delete WebAuthn credential

DELETE/v1/users/@me/mfa/webauthn/credentials/{credential_id}

MFA

Deletes a WebAuthn credential under sudo mode and returns 204. Deleting the last credential also turns off passkeys as a second factor, and without TOTP it deletes every backup code. Sends a WebAuthn Credentials Update Gateway event, and a User Update event when it deletes the last credential.

JSON body

The body is a sudo verification object.

Response

Status	Body	Condition
204	empty	The credential was deleted
404	error response	`UNKNOWN_WEBAUTHN_CREDENTIAL`

The rate limit is 10 requests per minute, on the mfa:webauthn:delete bucket.

Set WebAuthn two-factor authentication

PUT/v1/users/@me/mfa/webauthn/two-factor

MFA

Turns passkeys on or off as a second factor at password login. You need sudo mode, and turning it on also needs a verified account. Turning it on creates 10 backup codes when the account has no unused codes, and turning it off without TOTP deletes every backup code. Sends a User Update Gateway event when the setting changes.

JSON body

The body extends the sudo verification object with this field.

Field	Type	Description
enabled	boolean	Whether passkeys are a second factor at password login

Response

Status	Body	Condition
200	WebAuthn two-factor object	The setting was saved
400	error response	`NO_PASSKEYS_REGISTERED` when turning it on with no credentials
403	error response	`MFA_EMAIL_VERIFICATION_REQUIRED` or `ACCOUNT_VERIFICATION_REQUIRED` when turning it on and the account isn't verified

The rate limit is 10 requests per minute, on the mfa:webauthn:two_factor bucket.

Get sudo MFA methods

GET/v1/users/@me/sudo/mfa-methods

Returns the sudo mode proofs the account can give.

Response

Status	Body	Condition
200	sudo MFA methods object	The methods were returned

The rate limit is 20 requests per minute, on the sudo:mfa:methods bucket.

Send a sudo email code

POST/v1/users/@me/sudo/email-code

Emails a 6-digit code for sudo mode to an account that has no password and no second factor. The code lasts 10 minutes and allows 5 wrong tries.

Response

Status	Body	Condition
200	sudo email code object	The code was sent
400	error response	`SUDO_SECOND_FACTOR_REQUIRED` when the account has a second factor turned on
400	error response	`EMAIL_CODES_UNAVAILABLE` when the account has a password or no verified email address, or the instance doesn't send email
429	rate limit response	Too many codes were sent or too many wrong codes were tried

The rate limit is 5 requests per 15 minutes, on the sudo:email_code bucket.

Create sudo WebAuthn authentication options

POST/v1/users/@me/sudo/webauthn/authentication-options

Returns a sudo challenge that lists the account's passkeys. Send the signed result as webauthn_response and webauthn_challenge in a sudo verification object.

Response

Status	Body	Condition
200	WebAuthn authentication options object	The challenge was created
400	error response	`NO_PASSKEYS_REGISTERED`

The rate limit is 10 requests per minute, on the sudo:webauthn:options bucket.