A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Multi-factor authentication
description: TOTP, backup codes, WebAuthn credentials and sudo mode.
---
import RouteHeader from '@/components/RouteHeader.astro';
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](#sudo-mode) and passwordless login right away, but password login only asks for it after [Set WebAuthn two-factor authentication](#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](#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](#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.
1. [Start MFA backup codes challenge](#start-mfa-backup-codes-challenge) emails a code and returns a ticket that lasts 30 minutes.
2. [Verify MFA backup codes challenge code](#verify-mfa-backup-codes-challenge-code) trades the code, which lasts 10 minutes, for the current codes and a proof.
3. [Regenerate MFA backup codes](#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](/http-api/#validation-error-object).
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](#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](#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](#sudo-mode-methods-object) 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](/http-api/#error-response).
### Structure
| Field | Type | Description |
| --- | --- | --- |
| has_mfa | boolean | Whether the account has TOTP or at least one passkey |
| methods | [sudo mode method availability](#sudo-mode-method-availability-object) 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<sup>1</sup> | 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 |
<sup>1</sup> 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](#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](#webauthn-assertion-object) object | Assertion for `webauthn_challenge`, for `webauthn` |
| webauthn_challenge? | string | Challenge from [Create sudo WebAuthn authentication options](#create-sudo-webauthn-authentication-options) (1-256 characters) |
| email_code_ticket? | string | Ticket from [Send a sudo email code](#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](#mfa-backup-code-object) object] | The account's current backup codes |
### Example
```json
{
"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](#mfa-backup-code-object) object] | The account's current backup codes |
| verification_proof | string | The proof for [Regenerate MFA backup codes](#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](#webauthn-authenticator-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](#webauthn-assertion-response-object) object | Authenticator assertion response |
| authenticatorAttachment? | string | Either `cross-platform` or `platform` |
| clientExtensionResults | [WebAuthn client extension results](#webauthn-client-extension-results-object) 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](#webauthn-attestation-response-object) object | Authenticator attestation response |
| authenticatorAttachment? | string | Either `cross-platform` or `platform` |
| clientExtensionResults | [WebAuthn client extension results](#webauthn-client-extension-results-object) 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](#webauthn-authenticator-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](#webauthn-credential-properties-object) 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](/http-api/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](#webauthn-credential-descriptor-object) 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](#webauthn-relying-party-object) object | Relying party identity |
| user | [WebAuthn registration user](#webauthn-registration-user-object) object | The account the credential belongs to |
| challenge | string | Base64url one-use challenge, valid for five minutes |
| pubKeyCredParams | array[[WebAuthn public key parameter](#webauthn-public-key-parameter-object) object] | Accepted algorithms, COSE `-8`, `-7` and `-257` |
| timeout | integer | Authenticator timeout in milliseconds, always `60000` |
| excludeCredentials | array[[WebAuthn credential descriptor](#webauthn-credential-descriptor-object) object] | The account's existing credentials |
| authenticatorSelection | [WebAuthn authenticator selection](#webauthn-authenticator-selection-object) object | Authenticator requirements |
| attestation | string | Always `none` |
| extensions | [WebAuthn client extension inputs](#webauthn-client-extension-inputs-object) 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](/snowflakes/) 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](/http-api/users/#user-object) object | The updated account |
| backup_codes | ?array[[MFA backup code](#mfa-backup-code-object) object] | The 10 new codes, or null when the call created none |
## Enable TOTP MFA
<RouteHeader method="POST" path="/v1/users/@me/mfa/totp/enable" mfa />
Enables TOTP and returns 10 new backup codes. You need [sudo mode](#sudo-mode) and a [verified account](/http-api/users/#account-tiers). Sends a [User Update](/gateway/events/#user-update) Gateway event.
### JSON body
The body extends the [sudo verification object](#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](#mfa-backup-codes-object) object | TOTP was enabled |
| 400 | [error response](/http-api/#error-response) | `INVALID_CODE` on the path `code`, or `TWO_FA_ALREADY_ENABLED` when TOTP is already enabled |
| 403 | [error response](/http-api/#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
<RouteHeader method="POST" path="/v1/users/@me/mfa/totp/disable" mfa />
Disables TOTP under [sudo mode](#sudo-mode) and returns 204. This deletes every backup code unless passkeys stay on as a second factor. Sends a [User Update](/gateway/events/#user-update) Gateway event.
### JSON body
The body extends the [sudo verification object](#sudo-verification-object) with this field.
| Field | Type | Description |
| --- | --- | --- |
| code<sup>1</sup> | string | Current TOTP code or unused backup code (1-32 characters) |
<sup>1</sup> Without a sudo token or `mfa_method`, `code` also proves sudo mode
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | TOTP was disabled |
| 400 | [error response](/http-api/#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](/http-api/#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
<RouteHeader method="POST" path="/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](#sudo-mode), and replacing the codes also needs a [verified account](/http-api/users/#account-tiers).
### JSON body
The body extends the [sudo verification object](#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](#mfa-backup-codes-object) object | The current or new codes were returned |
| 403 | [error response](/http-api/#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
<RouteHeader method="POST" path="/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](#mfa-backup-codes-challenge-object) object | The code was sent |
| 400 | [error response](/http-api/#error-response) | `TWO_FACTOR_REQUIRED` when the account has no second factor turned on |
| 400 | [error response](/http-api/#error-response) | `EMAIL_CODES_UNAVAILABLE` when the instance doesn't send email |
| 403 | [error response](/http-api/#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
<RouteHeader method="POST" path="/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](#start-mfa-backup-codes-challenge) (1-256 characters) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | A new code was sent |
| 400 | [error response](/http-api/#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
<RouteHeader method="POST" path="/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](#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](#mfa-backup-codes-verification-object) object | The code was accepted |
| 400 | [error response](/http-api/#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
<RouteHeader method="POST" path="/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](#start-mfa-backup-codes-challenge) (1-256 characters) |
| verification_proof | string | Proof from [Verify MFA backup codes challenge code](#verify-mfa-backup-codes-challenge-code) (1-256 characters) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [MFA backup codes](#mfa-backup-codes-object) object | The codes were replaced |
| 400 | [error response](/http-api/#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
<RouteHeader method="GET" path="/v1/users/@me/mfa/webauthn/credentials" />
Returns the account's WebAuthn credentials.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[WebAuthn credential](#webauthn-credential-object) object] | The credentials were returned |
The rate limit is 40 requests per 10 seconds, on the `mfa:webauthn:list` bucket.
## Create WebAuthn registration options
<RouteHeader method="POST" path="/v1/users/@me/mfa/webauthn/credentials/registration-options" mfa />
Returns a registration challenge for [Register WebAuthn credential](#register-webauthn-credential). You need [sudo mode](#sudo-mode) and a [verified account](/http-api/users/#account-tiers) or one that only needs a password, and the response never has a sudo token.
### JSON body
The body is a [sudo verification object](#sudo-verification-object).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [WebAuthn registration options](#webauthn-registration-options-object) object | The challenge was created |
| 400 | [error response](/http-api/#error-response) | `WEBAUTHN_CREDENTIAL_LIMIT_REACHED` when the account has 10 credentials |
| 403 | [error response](/http-api/#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
<RouteHeader method="POST" path="/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/events/#webauthn-credentials-update) Gateway event, and a [User Update](/gateway/events/#user-update) event for the account's first credential.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| response | [WebAuthn registration response](#webauthn-registration-response-object) object | The authenticator's response to the challenge |
| challenge | string | Challenge from [Create WebAuthn registration options](#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](/http-api/#error-response) | `INVALID_WEBAUTHN_CREDENTIAL`, `INVALID_WEBAUTHN_PUBLIC_KEY_FORMAT` or `INVALID_WEBAUTHN_CREDENTIAL_COUNTER` |
| 400 | [error response](/http-api/#error-response) | `WEBAUTHN_CREDENTIAL_LIMIT_REACHED` when the account has 10 credentials |
| 403 | [error response](/http-api/#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
<RouteHeader method="PATCH" path="/v1/users/@me/mfa/webauthn/credentials/{credential_id}" mfa />
Renames a WebAuthn credential under [sudo mode](#sudo-mode) and returns 204. Sends a [WebAuthn Credentials Update](/gateway/events/#webauthn-credentials-update) Gateway event.
### JSON body
The body extends the [sudo verification object](#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](/http-api/#error-response) | `UNKNOWN_WEBAUTHN_CREDENTIAL` |
The rate limit is 20 requests per 10 seconds, on the `mfa:webauthn:update` bucket.
## Delete WebAuthn credential
<RouteHeader method="DELETE" path="/v1/users/@me/mfa/webauthn/credentials/{credential_id}" mfa />
Deletes a WebAuthn credential under [sudo mode](#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/events/#webauthn-credentials-update) Gateway event, and a [User Update](/gateway/events/#user-update) event when it deletes the last credential.
### JSON body
The body is a [sudo verification object](#sudo-verification-object).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The credential was deleted |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_WEBAUTHN_CREDENTIAL` |
The rate limit is 10 requests per minute, on the `mfa:webauthn:delete` bucket.
## Set WebAuthn two-factor authentication
<RouteHeader method="PUT" path="/v1/users/@me/mfa/webauthn/two-factor" mfa />
Turns passkeys on or off as a second factor at password login. You need [sudo mode](#sudo-mode), and turning it on also needs a [verified account](/http-api/users/#account-tiers). 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/events/#user-update) Gateway event when the setting changes.
### JSON body
The body extends the [sudo verification object](#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](#webauthn-two-factor-object) object | The setting was saved |
| 400 | [error response](/http-api/#error-response) | `NO_PASSKEYS_REGISTERED` when turning it on with no credentials |
| 403 | [error response](/http-api/#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
<RouteHeader method="GET" path="/v1/users/@me/sudo/mfa-methods" />
Returns the [sudo mode](#sudo-mode) proofs the account can give.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [sudo MFA methods](#sudo-mfa-methods-object) object | The methods were returned |
The rate limit is 20 requests per minute, on the `sudo:mfa:methods` bucket.
## Send a sudo email code
<RouteHeader method="POST" path="/v1/users/@me/sudo/email-code" />
Emails a 6-digit code for [sudo mode](#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](#sudo-email-code-object) object | The code was sent |
| 400 | [error response](/http-api/#error-response) | `SUDO_SECOND_FACTOR_REQUIRED` when the account has a second factor turned on |
| 400 | [error response](/http-api/#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](/topics/rate-limits/#rate-limit-response-object) | 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
<RouteHeader method="POST" path="/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](#sudo-verification-object).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [WebAuthn authentication options](#webauthn-authentication-options-object) object | The challenge was created |
| 400 | [error response](/http-api/#error-response) | `NO_PASSKEYS_REGISTERED` |
The rate limit is 10 requests per minute, on the `sudo:webauthn:options` bucket.