Skip to content

TOTP

reauth.factors.totp

TOTPAlgorithm 

TOTPAlgorithm = Literal['sha1', 'sha256', 'sha512']

TOTPEnrollment dataclass 

TOTPEnrollment(
    id: Any | None,
    identity_id: Any,
    enabled: bool,
    secret: str,
    algorithm: TOTPAlgorithm,
    code_length: int,
    time_step: int,
    last_verified_time_step: int | None = None,
)

id instance-attribute 

id: Any | None

identity_id instance-attribute 

identity_id: Any

enabled instance-attribute 

enabled: bool

secret instance-attribute 

secret: str

algorithm instance-attribute 

algorithm: TOTPAlgorithm

code_length instance-attribute 

code_length: int

time_step instance-attribute 

time_step: int

last_verified_time_step class-attribute instance-attribute 

last_verified_time_step: int | None = None

get_provisioning_uri 

get_provisioning_uri(
    account_name: str, issuer_name: str | None = None
) -> str

Get the provisioning URI for this TOTP factor.

Parameters:

Name Type Description Default
account_name str

The name of the account (e.g., email or username).

 required
issuer_name str | None

The name of the issuer (e.g., your service name).

 None

Returns:

Type Description
str

The provisioning URI that can be used to generate a QR code for enrollment in an authenticator app.

TOTPException 

TOTPException(message: str | None = None)

Bases: ReauthException

Base exception for TOTP errors.

InvalidTOTPCodeException 

InvalidTOTPCodeException(message: str | None = None)

Bases: TOTPException

Raised when a TOTP code is invalid.

AlreadyEnabledTOTPException 

AlreadyEnabledTOTPException(message: str | None = None)

Bases: TOTPException

Raised when trying to enable an already enabled TOTP factor.

NotEnabledTOTPException 

NotEnabledTOTPException(message: str | None = None)

Bases: TOTPException

Raised when trying to verify a TOTP factor that is not enabled.

AlreadyEnrolledTOTPException 

AlreadyEnrolledTOTPException(message: str | None = None)

Bases: TOTPException

Raised when trying to enroll an identity that already has a TOTP enrollment.

NotEnrolledTOTPException 

NotEnrolledTOTPException(message: str | None = None)

Bases: TOTPException

Raised when trying to enable or verify a TOTP factor for an identity with no enrollment.

TOTPFactor 

TOTPFactor(
    *,
    code_length: int = 6,
    algorithm: TOTPAlgorithm = "sha256",
    time_step: int = 30,
    drift_tolerance: int = 1,
    identifier: str = "totp",
    step: int = 1,
    advance_by: int = 1,
)

Bases: FactorBase[TOTPEnrollment], ABC

AMR class-attribute 

AMR: AuthenticationMethodReference = (
    AuthenticationMethodReference.OTP
)

code_length instance-attribute 

code_length = code_length

algorithm instance-attribute 

algorithm: TOTPAlgorithm = algorithm

time_step instance-attribute 

time_step = time_step

drift_tolerance instance-attribute 

drift_tolerance = drift_tolerance

get_enrollment async 

get_enrollment(identity_id: Any) -> TOTPEnrollment | None

Get the TOTP enrollment for a given identity, returning only enabled enrollments.

This method returns None for both non-existent enrollments and disabled enrollments. Use get_by_identity_id if you need to access disabled enrollments (e.g., during the enable flow).

Parameters:

Name Type Description Default
identity_id Any

The ID of the identity to get the TOTP enrollment for.

 required

Returns:

Type Description
TOTPEnrollment | None

The enabled TOTP enrollment for the identity, or None if no enrollment exists
TOTPEnrollment | None

or the enrollment is disabled.

enroll async 

enroll(identity_id: Any) -> TOTPEnrollment

Enroll a new TOTP factor for a given identity.

It starts in a disabled state, and must be enabled by verifying a first code with the enable method.

Parameters:

Name Type Description Default
identity_id Any

The ID of the identity to enroll the factor for.

 required

Returns:

Type Description
TOTPEnrollment

The enrolled TOTP factor.

Raises:

Type Description
AlreadyEnrolledTOTPException

If the identity already has a TOTP enrollment.

enable async 

enable(identity_id: Any, code: str) -> TOTPEnrollment

Enable a TOTP factor by verifying a provided OTP code against the expected value.

On success, the TOTP factor is marked as enabled and updated in the persistent store.

Parameters:

Name Type Description Default
identity_id Any

The ID of the identity to enable the TOTP factor for.

 required
code str

The OTP code provided by the user.

 required

Returns:

Type Description
TOTPEnrollment

The updated TOTP enrollment.

Raises:

Type Description
NotEnrolledTOTPException

If the identity has no TOTP enrollment.
AlreadyEnabledTOTPException

If the TOTP factor is already enabled.
InvalidTOTPCodeException

If the provided code is invalid.

verify async 

verify(identity_id: Any, code: str) -> TOTPEnrollment

Verify a provided OTP code against the expected value for the given TOTP factor.

Parameters:

Name Type Description Default
identity_id Any

The ID of the identity to verify the TOTP code for.

 required
code str

The OTP code provided by the user.

 required

Returns:

Type Description
TOTPEnrollment

The updated TOTP enrollment.

Raises:

Type Description
NotEnrolledTOTPException

If the identity has no TOTP enrollment.
NotEnabledTOTPException

If the TOTP factor is not enabled.
InvalidTOTPCodeException

If the provided code is invalid or has already been used.

get_by_identity_id abstractmethod async 

get_by_identity_id(
    identity_id: Any,
) -> TOTPEnrollment | None

Get the raw TOTP enrollment for a given identity, regardless of its enabled state.

This method is the primary data access point for implementers. It should retrieve the enrollment record from persistent storage without any filtering based on the enabled state.

The get_enrollment method uses this to provide a filtered view that excludes disabled enrollments.

Parameters:

Name Type Description Default
identity_id Any

The ID of the identity to get the TOTP enrollment for.

 required

Returns:

Type Description
TOTPEnrollment | None

The TOTP enrollment for the identity, or None if no enrollment exists.
TOTPEnrollment | None

This may return a disabled enrollment.

insert abstractmethod async 

insert(totp: TOTPEnrollment) -> typing.Any

Insert a TOTP factor into a persistent store.

update abstractmethod async 

update(totp: TOTPEnrollment) -> None

Update a TOTP factor in the persistent store.

delete abstractmethod async 

delete(totp: TOTPEnrollment) -> None

Delete a TOTP factor from the persistent store.