OATHTool

Common errors

• AttributeError: module 'oathtool' has no attribute 'TOTP'

  cause You are trying to import TOTP directly from the top-level `oathtool` module.
  fix Import TOTP from its specific submodule: `from oathtool.totp import TOTP`.

• ValueError: Invalid base32 secret

  cause The secret string provided to `TOTP` or `HOTP` constructor is not a valid base32 encoding.
  fix Verify that your secret key is a correctly formatted base32 string. It should only contain A-Z, 2-7, and optionally padding '=' characters.

• TypeError: oathtool.totp.TOTP.__init__() missing 1 required positional argument: 'key'

  cause No secret key was provided when initializing the `TOTP` or `HOTP` object.
  fix Pass your base32-encoded secret key as the first argument to the constructor, e.g., `TOTP('YOUR_SECRET_KEY')`.

Warnings

• gotcha Secret keys are typically expected to be base32-encoded strings. While `oathtool` can often handle raw bytes or attempt decoding, providing an invalid base32 string will lead to errors.
  Fix: Ensure your secret key is a valid base32-encoded string (e.g., from a QR code or provided by the service). Tools like `base64.b32decode` can verify format.
• gotcha Hardcoding secret keys directly in your code is a significant security risk. Anyone with access to your code can compromise your accounts.
  Fix: Always store secret keys securely. Use environment variables (as shown in quickstart), dedicated secret management services, or secure configuration files. For CLI, `oathtool` offers keyring integration.
• gotcha When using HOTP, the 'counter' value must be meticulously synchronized between the client (your application) and the server. Desynchronization will lead to invalid codes.
  Fix: Implement a robust mechanism to store and increment the HOTP counter reliably. Both client and server must agree on the current counter value. If out of sync, a resynchronization process is usually required.

Install

• pip install oathtool Install base library
• pip install 'oathtool[cli]' Install with CLI extras (keyring, clipboard)

Imports

• TOTP
  wrong:

  import oathtool; oathtool.TOTP

  correct:

  from oathtool.totp import TOTP

  TOTP is located in the `oathtool.totp` submodule, not directly under `oathtool`.
• HOTP
  wrong:

  import oathtool; oathtool.HOTP

  correct:

  from oathtool.hotp import HOTP

  HOTP is located in the `oathtool.hotp` submodule, not directly under `oathtool`.

Quickstart

This quickstart demonstrates how to generate a TOTP code using a base32-encoded secret key, typically obtained from a 2FA setup process. It emphasizes retrieving the secret securely from an environment variable and includes basic error handling for common key issues.

import os
from oathtool.totp import TOTP

# Retrieve your base32-encoded secret key from an environment variable.
# Example: 'JBSWY3DPEHPK3PXP' (this is a placeholder, use your actual secret)
secret_base32 = os.environ.get('OATHTOOL_SECRET', 'JBSWY3DPEHPK3PXP')

if secret_base32 == 'JBSWY3DPEHPK3PXP':
    print("WARNING: Using a placeholder secret. Set OATHTOOL_SECRET environment variable for actual use.")

try:
    # Initialize the TOTP generator with your secret.
    # oathtool expects the secret to be base32-encoded or raw bytes.
    # If a base32 string is provided, it will be decoded automatically.
    totp = TOTP(secret_base32)

    # Generate the current time-based one-time password.
    current_otp = totp.code()
    print(f"Generated TOTP: {current_otp}")

    # You can also get the remaining time until the next code.
    # time_left = totp.time_left()
    # print(f"Time left until next code: {time_left} seconds")

except Exception as e:
    print(f"Error generating OTP: {e}")
    print("Ensure your OATHTOOL_SECRET is a valid base32 encoded string.")