Time-based OTPs

import pyotp

totp = pyotp.TOTP('base32secret32323232323232')
totp.now()  # Current OTP; changes with the clock.

# A fixed Unix timestamp makes these example outputs reproducible.
totp.at(1234567890) # => '763850'
totp.verify('763850', for_time=1234567890) # => True
totp.verify('763850', for_time=1234567920) # => False

Preventing replay attacks

TOTP.verify() and TOTP.verify_and_get_timecode() are stateless: they can accept the same OTP repeatedly while it remains valid. To prevent reuse, call verify_and_get_timecode() and persist its returned timecode for each credential in a database shared by all application workers. The timecode identifies the matching TOTP interval; it is not the wall-clock timestamp when verification occurred. Reject a timecode that is less than or equal to the last accepted timecode.

verify_and_get_timecode() raises pyotp.OTPVerificationError (a subclass of pyotp.PyOTPError) if the OTP does not match within the allowed window. Successful verification always returns an integer timecode.

The check and update must be atomic, so two concurrent requests cannot both accept the same timecode. For example, the following function uses a sqlite3.Connection named db and a totp_credentials table with one existing row per credential, an id primary key, and a nullable integer last_timecode column. Initialize last_timecode to NULL for a new credential. totp and credential_id must refer to the same credential.

import pyotp

def verify_totp_once(db, credential_id, totp, otp):
    try:
        matched_timecode = totp.verify_and_get_timecode(otp)
    except pyotp.OTPVerificationError:
        return False

    with db:
        updated = db.execute(
            "UPDATE totp_credentials SET last_timecode = ? "
            "WHERE id = ? AND (last_timecode IS NULL OR last_timecode < ?)",
            (matched_timecode, credential_id, matched_timecode),
        )
    return updated.rowcount == 1

Grant authentication only when this function returns True, after the database transaction has committed. If you enable valid_window, persist the returned matching timecode, which may differ from the server’s current timecode.

Counter-based OTPs

import pyotp

hotp = pyotp.HOTP('base32secret32323232323232')
hotp.at(0) # => '995369'
hotp.at(1) # => '511453'
hotp.at(1401) # => '666948'

# OTP verified with a counter
hotp.verify('666948', 1401) # => True
hotp.verify('666948', 1402) # => False

Generating a Secret Key

A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other OTP apps:

pyotp.random_base32()

Some applications want the secret key to be formatted as a hex-encoded string:

pyotp.random_hex()  # returns a 40-character hex-encoded secret

Google Authenticator Compatible

PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps:

pyotp.totp.TOTP('JBSWY3DPEHPK3PXPJBSWY3DP').provisioning_uri(name='alice@google.com', issuer_name='Secure App')

>>> 'otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App'

pyotp.hotp.HOTP('JBSWY3DPEHPK3PXPJBSWY3DP').provisioning_uri(name="alice@google.com", issuer_name="Secure App", initial_count=0)

>>> 'otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App&counter=0'

This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode) which can then be scanned and added to the users list of OTP credentials.

Parsing these URLs is also supported:

pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App')

>>> <pyotp.totp.TOTP object at 0xFFFFFFFF>

pyotp.parse_uri('otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App&counter=0')

>>> <pyotp.hotp.HOTP object at 0xFFFFFFFF>

Working example

Scan the following barcode with your phone’s OTP app (e.g. Google Authenticator):

Now run the following and compare the output:

import pyotp
totp = pyotp.TOTP("JBSWY3DPEHPK3PXPJBSWY3DP")
print("Current OTP:", totp.now())

Third-party contributions

The following third-party contributions are not described by a standard, not officially supported, and provided for reference only:

• pyotp.contrib.Steam(): An implementation of Steam TOTP. Uses the same API as pyotp.TOTP().

Links

• Project home page (GitHub)

• Documentation

• Package distribution (PyPI)

• Change log

• RFC 4226: HOTP: An HMAC-Based One-Time Password

• RFC 6238: TOTP: Time-Based One-Time Password Algorithm

• ROTP - Original Ruby OTP library by Mark Percival

• OTPHP - PHP port of ROTP by Le Lag

• OWASP Authentication Cheat Sheet

• NIST SP 800-63 Digital Identity Guidelines

For new applications:

• WebAuthn

• PyWARP

Versioning

This package follows the Semantic Versioning 2.0.0 standard. To control changes, it is recommended that application developers pin the package version and manage it using pip-tools or similar. For library developers, pinning the major version is recommended.