API Reference

Sign-up tokens module for user registration.

This module provides CRUD operations, email messaging, and utilities for sign-up token management.

Exports

• CRUD: create_sign_up_token, get_sign_up_token_by_hash, mark_sign_up_token_used, delete_expired_sign_up_tokens
• Schemas: SignUpToken, SignUpConfirm, SignUpResponse
• Models: SignUpToken (ORM model)

SignUpConfirm

Bases: BaseModel

Request schema for confirming a sign-up.

Attributes:

Name	Type	Description
token	StrictStr	The sign-up token received by user.

Source code in backend/app/sign_up_tokens/schema.py

class SignUpConfirm(BaseModel):
    """
    Request schema for confirming a sign-up.

    Attributes:
        token: The sign-up token received by user.
    """

    token: StrictStr = Field(
        ...,
        description=("The sign-up token received by the user"),
        min_length=1,
        max_length=256,
    )

    model_config = ConfigDict(extra="forbid")

SignUpResponse

Bases: BaseModel

Response schema for sign-up operations.

Attributes:

Name	Type	Description
message	StrictStr	Human-readable result message.
email_verification_required	StrictBool | None	Whether email verification is required.
admin_approval_required	StrictBool | None	Whether admin approval is required.

Source code in backend/app/sign_up_tokens/schema.py

class SignUpResponse(BaseModel):
    """
    Response schema for sign-up operations.

    Attributes:
        message: Human-readable result message.
        email_verification_required: Whether email verification is required.
        admin_approval_required: Whether admin approval is required.
    """

    message: StrictStr = Field(
        ...,
        description="Human-readable result message",
    )
    email_verification_required: StrictBool | None = Field(
        default=None,
        description=("Whether email verification is required"),
    )
    admin_approval_required: StrictBool | None = Field(
        default=None,
        description=("Whether admin approval is required"),
    )

    model_config = ConfigDict(extra="forbid")

SignUpToken

Bases: BaseModel

Schema representing a sign-up token record.

Attributes:

Name	Type	Description
id	StrictStr	Unique identifier for the token.
user_id	StrictInt	ID of the user who signed up.
token_hash	StrictStr	Hashed token value.
created_at	datetime	Timestamp when token was created.
expires_at	datetime	Timestamp when the token expires.
used	StrictBool	Whether the token has been used.

Source code in backend/app/sign_up_tokens/schema.py

class SignUpToken(BaseModel):
    """
    Schema representing a sign-up token record.

    Attributes:
        id: Unique identifier for the token.
        user_id: ID of the user who signed up.
        token_hash: Hashed token value.
        created_at: Timestamp when token was created.
        expires_at: Timestamp when the token expires.
        used: Whether the token has been used.
    """

    id: StrictStr = Field(
        ...,
        description="Unique identifier for the token",
        max_length=64,
    )
    user_id: StrictInt = Field(
        ...,
        description="ID of the user who signed up",
    )
    token_hash: StrictStr = Field(
        ...,
        description="Hashed token value",
        max_length=128,
    )
    created_at: datetime = Field(
        ...,
        description=("Timestamp when the token was created"),
    )
    expires_at: datetime = Field(
        ...,
        description=("Timestamp when the token expires"),
    )
    used: StrictBool = Field(
        ...,
        description="Whether the token has been used",
    )

    model_config = ConfigDict(
        from_attributes=True,
        extra="forbid",
        validate_assignment=True,
    )

SignUpTokenModel

Bases: Base

Sign-up token database model.

Attributes:

Name	Type	Description
id	Mapped[str]	Unique token identifier (string, 64 chars).
user_id	Mapped[int]	ID of the user who owns the token.
token_hash	Mapped[str]	Hashed sign-up token.
created_at	Mapped[datetime]	Token creation date.
expires_at	Mapped[datetime]	Token expiration date.
used	Mapped[bool]	Whether the token has been used.
users	Mapped[Users]	Relationship to the Users model.

Source code in backend/app/sign_up_tokens/models.py

class SignUpToken(Base):
    """
    Sign-up token database model.

    Attributes:
        id: Unique token identifier (string, 64 chars).
        user_id: ID of the user who owns the token.
        token_hash: Hashed sign-up token.
        created_at: Token creation date.
        expires_at: Token expiration date.
        used: Whether the token has been used.
        users: Relationship to the Users model.
    """

    __tablename__ = "sign_up_tokens"

    id: Mapped[str] = mapped_column(String(64), primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
        comment=("User ID that the sign up token belongs to"),
    )
    token_hash: Mapped[str] = mapped_column(
        String(128),
        nullable=False,
        comment="Hashed sign up token",
    )
    created_at: Mapped[datetime_type] = mapped_column(
        DateTime(timezone=True),
        nullable=False,
        comment="Token creation date (datetime)",
    )
    expires_at: Mapped[datetime_type] = mapped_column(
        DateTime(timezone=True),
        nullable=False,
        comment="Token expiration date (datetime)",
    )
    used: Mapped[bool] = mapped_column(
        default=False,
        nullable=False,
        comment="Token usage status",
    )

    # Define a relationship to the Users model
    users: Mapped["Users"] = relationship(back_populates="sign_up_tokens")

create_sign_up_token

create_sign_up_token(token, db)

Create and persist a new sign-up token.

Parameters:

Name	Type	Description	Default
token	SignUpToken	Schema object with token data to persist.	required
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
SignUpToken	The persisted SignUpToken ORM instance.

Raises:

Type	Description
HTTPException	500 error if database operation fails.

Source code in backend/app/sign_up_tokens/crud.py

@core_decorators.handle_db_errors
def create_sign_up_token(
    token: sign_up_tokens_schema.SignUpToken,
    db: Session,
) -> sign_up_tokens_models.SignUpToken:
    """Create and persist a new sign-up token.

    Args:
        token: Schema object with token data to persist.
        db: SQLAlchemy database session.

    Returns:
        The persisted SignUpToken ORM instance.

    Raises:
        HTTPException: 500 error if database operation fails.
    """
    db_token = sign_up_tokens_models.SignUpToken(
        id=token.id,
        user_id=token.user_id,
        token_hash=token.token_hash,
        created_at=token.created_at,
        expires_at=token.expires_at,
        used=token.used,
    )
    db.add(db_token)
    db.commit()
    db.refresh(db_token)
    return db_token

delete_expired_sign_up_tokens

delete_expired_sign_up_tokens(db)

Delete all expired sign-up tokens.

Parameters:

Name	Type	Description	Default
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
int	Number of deleted rows.

Raises:

Type	Description
HTTPException	500 error if database operation fails.

Source code in backend/app/sign_up_tokens/crud.py

@core_decorators.handle_db_errors
def delete_expired_sign_up_tokens(db: Session) -> int:
    """Delete all expired sign-up tokens.

    Args:
        db: SQLAlchemy database session.

    Returns:
        Number of deleted rows.

    Raises:
        HTTPException: 500 error if database operation fails.
    """
    stmt = sa_delete(sign_up_tokens_models.SignUpToken).where(
        sign_up_tokens_models.SignUpToken.expires_at < datetime.now(timezone.utc)
    )
    result = db.execute(stmt)
    db.commit()
    return result.rowcount

get_sign_up_token_by_hash

get_sign_up_token_by_hash(token_hash, db)

Retrieve an unused, unexpired token matching the hash.

Parameters:

Name	Type	Description	Default
token_hash	str	The hashed token value to look up.	required
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
SignUpToken | None	The matching SignUpToken if found and valid,
SignUpToken | None	None otherwise.

Raises:

Type	Description
HTTPException	500 error if database query fails.

Source code in backend/app/sign_up_tokens/crud.py

@core_decorators.handle_db_errors
def get_sign_up_token_by_hash(
    token_hash: str, db: Session
) -> sign_up_tokens_models.SignUpToken | None:
    """Retrieve an unused, unexpired token matching the hash.

    Args:
        token_hash: The hashed token value to look up.
        db: SQLAlchemy database session.

    Returns:
        The matching SignUpToken if found and valid,
        None otherwise.

    Raises:
        HTTPException: 500 error if database query fails.
    """
    stmt = select(sign_up_tokens_models.SignUpToken).where(
        sign_up_tokens_models.SignUpToken.token_hash == token_hash,
        sign_up_tokens_models.SignUpToken.used.is_(False),
        sign_up_tokens_models.SignUpToken.expires_at > datetime.now(timezone.utc),
    )
    return db.execute(stmt).scalar_one_or_none()

mark_sign_up_token_used

mark_sign_up_token_used(token_id, db)

Mark a sign-up token as used.

Parameters:

Name	Type	Description	Default
token_id	str	The unique identifier of the token.	required
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
SignUpToken | None	Updated SignUpToken instance if found,
SignUpToken | None	None otherwise.

Raises:

Type	Description
HTTPException	500 error if database operation fails.

Source code in backend/app/sign_up_tokens/crud.py

@core_decorators.handle_db_errors
def mark_sign_up_token_used(
    token_id: str, db: Session
) -> sign_up_tokens_models.SignUpToken | None:
    """Mark a sign-up token as used.

    Args:
        token_id: The unique identifier of the token.
        db: SQLAlchemy database session.

    Returns:
        Updated SignUpToken instance if found,
        None otherwise.

    Raises:
        HTTPException: 500 error if database operation fails.
    """
    stmt = select(sign_up_tokens_models.SignUpToken).where(
        sign_up_tokens_models.SignUpToken.id == token_id,
    )
    db_token = db.execute(stmt).scalar_one_or_none()

    if db_token:
        db_token.used = True
        db.commit()
        db.refresh(db_token)

    return db_token