Two-Factor Authentication API

Configure and manage two-factor authentication methods

Overview

Bitwarden supports multiple two-factor authentication (2FA) providers to enhance account security.

Supported Providers

• Authenticator App (TOTP)
• Email
• Duo Security
• YubiKey
• WebAuthn (FIDO2)

List Two-Factor Providers

Get all configured two-factor providers for the authenticated user.

GET /two-factor

Response

Returns a list of enabled two-factor providers with their configurations.

---

Authenticator (TOTP)

Get Authenticator Setup

Retrieve the secret key and QR code for setting up authenticator apps.

POST /two-factor/get-authenticator

secret · string · required

Master password hash for verification

Response

key · string · required

Base32-encoded secret key

qr · string · required

SVG QR code for scanning

userVerificationToken · string · required

Token for completing setup

Enable Authenticator

PUT /two-factor/authenticator

token · string · required

6-digit code from authenticator app

key · string · required

Secret key from setup

userVerificationToken · string · required

Verification token from setup

Disable Authenticator

DELETE /two-factor/authenticator

type · number · required

Provider type (0 for Authenticator)

key · string · required

Secret key

userVerificationToken · string · required

Verification token

---

Email 2FA

Get Email Configuration

POST /two-factor/get-email

secret · string · required

Master password hash

Send Setup Email

POST /two-factor/send-email

email · string · required

Email address to use for 2FA

secret · string · required

Master password hash

Enable Email 2FA

PUT /two-factor/email

email · string · required

Email address for 2FA

token · string · required

6-digit code from email

secret · string · required

Master password hash

---

Duo Security

Get Duo Configuration

POST /two-factor/get-duo

secret · string · required

Master password hash

Enable Duo

PUT /two-factor/duo

clientId · string · required

Duo client ID

clientSecret · string · required

Duo client secret

host · string · required

Duo API hostname

secret · string · required

Master password hash

---

Organization Duo

Get Organization Duo Configuration

POST /organizations/{id}/two-factor/get-duo

id · string · required

Organization ID

Enable Organization Duo

PUT /organizations/{id}/two-factor/duo

id · string · required

Organization ID

clientId · string · required

Duo client ID

clientSecret · string · required

Duo client secret

host · string · required

Duo API hostname

Disable Organization Duo

PUT /organizations/{id}/two-factor/disable

id · string · required

Organization ID

type · number · required

Provider type (6 for OrganizationDuo)

---

YubiKey

Get YubiKey Configuration

POST /two-factor/get-yubikey

secret · string · required

Master password hash

Enable YubiKey

PUT /two-factor/yubikey

key1 · string

First YubiKey OTP (12 characters)

key2 · string

Second YubiKey OTP (optional)

key3 · string

Third YubiKey OTP (optional)

key4 · string

Fourth YubiKey OTP (optional)

key5 · string

Fifth YubiKey OTP (optional)

nfc · boolean

Whether NFC is supported

secret · string · required

Master password hash

You can register up to 5 YubiKeys. The first key is required, others are optional backups.

---

WebAuthn (FIDO2)

Get WebAuthn Configuration

POST /two-factor/get-webauthn

secret · string · required

Master password hash

Start WebAuthn Registration

POST /two-factor/get-webauthn-challenge

secret · string · required

Master password hash

Response

Returns a challenge object compatible with navigator.credentials.create().

Complete WebAuthn Registration

PUT /two-factor/webauthn

id · number · required

Credential ID

name · string · required

Friendly name for the security key

deviceResponse · object · required

Response from navigator.credentials.create()

secret · string · required

Master password hash

Delete WebAuthn Credential

DELETE /two-factor/webauthn

id · number · required

Credential ID to delete

secret · string · required

Master password hash

---

Disable Two-Factor Provider

Disable a specific two-factor provider.

PUT /two-factor/disable

type · number · required

Provider type to disable

secret · string · required

Master password hash

Provider Types

• 0 - Authenticator
• 1 - Email
• 2 - Duo
• 3 - YubiKey
• 4 - U2F (deprecated)
• 5 - Remember
• 6 - OrganizationDuo
• 7 - WebAuthn

---

Get Recovery Code

Retrieve the two-factor recovery code.

POST /two-factor/get-recover

secret · string · required

Master password hash

Response

code · string

Recovery code for bypassing 2FA

Store your recovery code in a safe place. It can be used to access your account if you lose access to all 2FA methods.