How to setup TOTP in KeePassium

KeePassium can generate time-based one-time passwords (TOTP) for services that require two-factor authentication (2FA). For security reasons, you should not keep your passwords and TOTP tokens in the same database.

Compatibility

TOTP codes added by KeePassium are compatible with KeePassXC and most mobile apps. For KeePass, however, you would need the KeePassOTP plugin.

Setup

Using a QR code

This is the easiest and quickest method:

  • Open the entry editor and tap Set up one-time password (OTP) → Scan QR Code
  • Point the camera to the QR code shown by the target website

The QR code should contain an otpauth:// URI (a de facto standard for 2FA QR codes). KeePassium will save the configuration URI to a custom field named otp.

Using a secret key (token)

If you run KeePassium on a computer and cannot scan QR codes, there is an alternative setup method.

  • On the target website, select the option to enter the TOTP secret code manually:
    TOTP secret key for a Google Account
    TOTP secret key for a Google Account
  • Copy the secret code to clipboard
  • In KeePassium, open the entry editor and tap Set up one-time password (OTP) → Enter manually
  • Paste the secret code into the app (spaces and capitalization don’t matter)

The result should look like this:

Working TOTP setup in KeePassium
Working TOTP setup in KeePassium

Using an otpauth URI

Some websites will provide you an otpauth:// URI instead of the secret code:

TOTP setup for Mailbox.org
TOTP setup for Mailbox.org
  • Copy the otpauth link to clipboard
  • Open the entry editor → Set up one-time password (OTP) → Enter manually
  • Paste the link into the “Enter secret code” field.

Steam TOTP setup

Valve’s Steam service has its own TOTP format. KeePassium can generate Steam TOTP codes, too.

Open the Steam entry in your database and create two custom fields:

  • TOTP Settings with value 30;S (30 is the refresh interval, and S means that TOTP codes should have Steam-specific format)
  • TOTP Seed with the secret key (in base32 format)

There is no easy way to extract Steam’s secret key, but this is possible. For more details, please follow this guide: How to get your Steam shared_secret key).

Troubleshooting

TOTP setup button is missing

Your database file uses an old format that does not support custom entry fields. As a solution, upgrade your database to KDBX format.

Generated TOTP codes seem invalid

  • Make sure the system time on your device is correct. Even a 30-second deviation can make generated codes invalid.
  • Check the entered secret key for possible typos. Spaces and capitalization do not matter.

Last Updated: 2023-05-08