Skip to content

HOTP

reauth.factors.hotp

HOTPAlgorithm 

HOTPAlgorithm = Literal['sha1']

HOTPEnrollment dataclass 

HOTPEnrollment(
    id: Any | None,
    identity_id: Any,
    enabled: bool,
    secret: str,
    algorithm: HOTPAlgorithm,
    code_length: int,
    counter: int,
)

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: HOTPAlgorithm

code_length instance-attribute 

code_length: int

counter instance-attribute 

counter: int

get_provisioning_uri 

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

Get the provisioning URI for this HOTP 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.

HOTPException 

HOTPException(message: str | None = None)

Bases: ReauthException

Base exception for HOTP errors.

AlreadyEnabledHOTPException 

AlreadyEnabledHOTPException(message: str | None = None)

Bases: HOTPException

Raised when trying to enable an already enabled HOTP factor.

NotEnabledHOTPException 

NotEnabledHOTPException(message: str | None = None)

Bases: HOTPException

Raised when trying to verify an HOTP factor that is not enabled.

InvalidHOTPCodeException 

InvalidHOTPCodeException(message: str | None = None)

Bases: HOTPException

Raised when an HOTP code is invalid.

AlreadyEnrolledHOTPException 

AlreadyEnrolledHOTPException(message: str | None = None)

Bases: HOTPException

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

NotEnrolledHOTPException 

NotEnrolledHOTPException(message: str | None = None)

Bases: HOTPException

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

HOTPFactor 

HOTPFactor(
    *,
    code_length: int = 6,
    algorithm: HOTPAlgorithm = "sha1",
    look_ahead: int = 5,
    identifier: str = "hotp",
    step: int = 1,
    advance_by: int = 1,
)

Bases: FactorBase[HOTPEnrollment], ABC

AMR class-attribute 

AMR: AuthenticationMethodReference = (
    AuthenticationMethodReference.OTP
)

code_length instance-attribute 

code_length = code_length

algorithm instance-attribute 

algorithm: HOTPAlgorithm = algorithm

look_ahead instance-attribute 

look_ahead = look_ahead

get_enrollment async 

get_enrollment(identity_id: Any) -> HOTPEnrollment | None

Get the HOTP 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 HOTP enrollment for.

 required

Returns:

Type Description
HOTPEnrollment | None

The enabled HOTP enrollment for the identity, or None if no enrollment exists
HOTPEnrollment | None

or the enrollment is disabled.

enroll async 

enroll(identity_id: Any) -> HOTPEnrollment

Enroll a new HOTP 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
HOTPEnrollment

The enrolled HOTP factor.

Raises:

Type Description
AlreadyEnrolledHOTPException

If the identity already has an HOTP enrollment.

enable async 

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

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

On success, the HOTP 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 HOTP factor for.

 required
code str

The OTP code provided by the user.

 required

Returns:

Type Description
HOTPEnrollment

The updated HOTP enrollment.

Raises:

Type Description
NotEnrolledHOTPException

If the identity has no HOTP enrollment.
AlreadyEnabledHOTPException

If the HOTP factor is already enabled.
InvalidHOTPCodeException

If the provided code is invalid.

verify async 

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

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

On success, the counter is incremented and the HOTP factor is updated in the persistent store.

Parameters:

Name Type Description Default
identity_id Any

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

 required
code str

The OTP code provided by the user.

 required

Returns:

Type Description
HOTPEnrollment

The updated HOTP enrollment.

Raises:

Type Description
NotEnrolledHOTPException

If the identity has no HOTP enrollment.
NotEnabledHOTPException

If the HOTP factor is not enabled.
InvalidHOTPCodeException

If the provided code is invalid.

get_by_identity_id abstractmethod async 

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

Get the raw HOTP 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 HOTP enrollment for.

 required

Returns:

Type Description
HOTPEnrollment | None

The HOTP enrollment for the identity, or None if no enrollment exists.
HOTPEnrollment | None

This may return a disabled enrollment.

insert abstractmethod async 

insert(hotp: HOTPEnrollment) -> typing.Any

Insert an HOTP factor into a persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
hotp HOTPEnrollment

The HOTP factor to insert.

 required

Returns:

Type Description
Any

The ID of the inserted HOTP factor.

update abstractmethod async 

update(hotp: HOTPEnrollment) -> None

Update an HOTP factor in the persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
hotp HOTPEnrollment

The HOTP factor to update.

 required

delete abstractmethod async 

delete(hotp: HOTPEnrollment) -> None

Delete an HOTP factor from the persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
hotp HOTPEnrollment

The HOTP factor to delete.

 required