Skip to content

Email OTP

reauth.factors.email_otp

EmailOTPEnrollment dataclass 

EmailOTPEnrollment(
    id: Any | None, identity_id: Any, email: str
)

id instance-attribute 

id: Any | None

identity_id instance-attribute 

identity_id: Any

email instance-attribute 

email: str

EmailOTP dataclass 

EmailOTP(
    id: Any | None,
    identity_id: Any | None,
    email: str,
    code_hash: str,
    expires_at: int,
    authentication_session_id: Any,
)

id instance-attribute 

id: Any | None

identity_id instance-attribute 

identity_id: Any | None

email instance-attribute 

email: str

code_hash instance-attribute 

code_hash: str

expires_at instance-attribute 

expires_at: int

authentication_session_id instance-attribute 

authentication_session_id: Any

is_expired 

is_expired() -> bool

Check if the OTP has expired.

Returns:

Type Description
bool

True if the OTP has expired, False otherwise.

EmailOTPException 

EmailOTPException(message: str | None = None)

Bases: ReauthException

Base exception for email OTP errors.

InvalidOTPException 

InvalidOTPException(message: str | None = None)

Bases: EmailOTPException

Raised when an OTP code is invalid.

ExpiredOTPException 

ExpiredOTPException(message: str | None = None)

Bases: EmailOTPException

Raised when an OTP code has expired.

EmailOTPFactor 

EmailOTPFactor(
    *,
    hash_secret: str,
    code_length: int = 6,
    lifetime: timedelta = datetime.timedelta(minutes=10),
    identifier: str = "email_otp",
    step: int = 0,
    advance_by: int = 1,
)

Bases: FactorBase[EmailOTPEnrollment], ABC

AMR class-attribute 

AMR: AuthenticationMethodReference = (
    AuthenticationMethodReference.EMAIL
)

hash_secret instance-attribute 

hash_secret = hash_secret

code_length instance-attribute 

code_length = code_length

lifetime instance-attribute 

lifetime = lifetime

create async 

create(
    email: str,
    authentication_session_id: Any,
    identity_id: Any | None = None,
) -> tuple[str, EmailOTP]

Create a new OTP for the given identity.

If an existing OTP for the same authentication session exists, it's deleted and replaced with the new one.

Parameters:

Name Type Description Default
email str

The email address this OTP is sent to.

 required
authentication_session_id Any

The ID of the authentication session this OTP is associated with.

 required
identity_id Any | None

Optional ID of the identity to create the OTP for. Can be None for signup flows.

 None

Returns:

Type Description
tuple[str, EmailOTP]

A tuple of (OTP code, EmailOTP instance).

consume async 

consume(
    code: str, authentication_session_id: Any
) -> tuple[typing.Any | None, str]

Consume an OTP code, deleting it from the persistent store if valid.

Parameters:

Name Type Description Default
code str

The OTP code to consume.

 required
authentication_session_id Any

The ID of the authentication session this OTP is associated with.

 required

Returns:

Type Description
Any | None

A tuple of (identity_id, email). identity_id is None for new users (signup flow).
str

For signup flows where identity_id is None, the application MUST create an
tuple[Any | None, str]

identity and EmailOTPEnrollment after successful OTP verification.

Raises:

Type Description
InvalidOTPException

If the code is invalid or does not correspond to any OTP.
ExpiredOTPException

If the OTP has expired.

insert abstractmethod async 

insert(email_otp: EmailOTP) -> typing.Any

Insert an EmailOTP instance into a persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
email_otp EmailOTP

The EmailOTP instance to insert.

 required

Returns:

Type Description
Any

The ID of the inserted EmailOTP.

get_by_code_hash_and_authentication_session_id abstractmethod async 

get_by_code_hash_and_authentication_session_id(
    code_hash: str, authentication_session_id: Any
) -> EmailOTP | None

Retrieve an EmailOTP instance by its code hash from the persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
code_hash str

The hash of the OTP code to retrieve.

 required
authentication_session_id Any

The ID of the authentication session this OTP is associated with.

 required

Returns:

Type Description
EmailOTP | None

The corresponding EmailOTP instance, or None if not found.

delete abstractmethod async 

delete(email_otp: EmailOTP) -> None

Delete an EmailOTP instance from the persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
email_otp EmailOTP

The EmailOTP instance to delete.

 required

delete_by_authentication_session_id abstractmethod async 

delete_by_authentication_session_id(
    authentication_session_id: Any,
) -> None

Delete all EmailOTP instances associated with a given authentication session ID.

Implementers should implement this method.

Parameters:

Name Type Description Default
authentication_session_id Any

The ID of the authentication session to delete OTPs for.

 required