User Management¶

User management covers the full lifecycle: registration, authentication, profile updates, and deletion. This page documents the endpoints and patterns the boilerplate ships with.

Endpoints at a Glance¶

All under /api/v1/users/ (defined in modules/user/routes.py):

Plus the auth endpoints under /api/v1/auth/ documented in Sessions.

Registration¶

POST /api/v1/users/ is open — no auth required. Anyone can create an account.

curl -X POST http://localhost:8000/api/v1/users/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "password": "Str1ngst!"
  }'

The route delegates to UserService.create, which:

1. Checks email is unique → raises UserExistsError if not (→ 409)
2. Checks username is unique → raises UserExistsError if not (→ 409)
3. Hashes the password with bcrypt via get_password_hash
4. Builds a UserCreateInternal (schema with hashed_password instead of password)
5. Persists via crud_users.create

# modules/user/service.py
async def create(self, user: UserCreate, db: AsyncSession) -> dict[str, Any]:
    if await crud_users.exists(db=db, email=user.email):
        raise UserExistsError("Email already registered")
    if await crud_users.exists(db=db, username=user.username):
        raise UserExistsError("Username already taken")

    payload = user.model_dump()
    payload["hashed_password"] = get_password_hash(payload.pop("password"))
    user_internal = UserCreateInternal(**payload)

    return await crud_users.create(db=db, object=user_internal, schema_to_select=UserRead)

The UserCreate schema enforces input validation:

class UserCreate(UserBase):
    model_config = ConfigDict(extra="forbid")

    password: Annotated[
        str,
        Field(
            min_length=8,
            pattern=r"^.{8,}|[0-9]+|[A-Z]+|[a-z]+|[^a-zA-Z0-9]+$",
            examples=["Str1ngst!"],
        ),
    ]
    # OAuth fields (filled when user signs up via Google)
    google_id: str | None = None
    github_id: str | None = None
    oauth_provider: str | None = None

extra="forbid" rejects any unknown fields the client tries to send — useful to keep clients honest.

Authentication¶

Authentication happens via POST /api/v1/auth/login. See Sessions for the full flow. The credential check itself now lives inside the crudauth library — the login route delegates to the auth singleton (infrastructure/auth/setup.py), which looks the user up, verifies the password, and creates the session. The boilerplate no longer ships an authenticate_user helper.

Two things to note about the login behavior:

• Username or email — both forms work in the same field
• Soft-deleted users can't log in — crudauth reads User.is_active (defined as not is_deleted), so deactivated accounts are rejected before the password is even checked

Password Hashing (bcrypt)¶

Password hashing helpers come from crudauth:

from crudauth import get_password_hash, verify_password

hashed = get_password_hash("plaintext")          # bcrypt, salt generated automatically
ok = await verify_password("plaintext", hashed)  # constant-time compare

bcrypt handles salt generation automatically and is computationally expensive enough to defeat brute force at scale. UserService.create uses get_password_hash when persisting a new account (see Registration).

Profile Operations¶

Get Current User¶

curl http://localhost:8000/api/v1/users/me -b cookies.txt

Trivial route — get_current_user already returns the user dict:

@router.get("/me", response_model=UserRead)
async def get_current_user_profile(
    current_user: Annotated[dict[str, Any], Depends(get_current_user)],
) -> dict[str, Any]:
    return current_user

Get User by Username¶

Public endpoint — no auth required. Filters out soft-deleted users.

curl http://localhost:8000/api/v1/users/johndoe

Returns 404 if not found or soft-deleted. The admin-only /active-and-inactive/{username} variant returns soft-deleted users too.

Update Profile¶

Users can update their own profile; superusers can update anyone's. Tier updates are gated on a separate endpoint (see Permissions).

curl -X PATCH http://localhost:8000/api/v1/users/johndoe \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: <token>" \
  -d '{"name": "John Updated"}'

The service enforces the ownership rule:

# modules/user/service.py
async def verify_user_permission(
    self, current_user: dict[str, Any], target_username: str, action: str,
) -> None:
    if current_user["username"] != target_username and not current_user["is_superuser"]:
        raise PermissionDeniedError(f"Cannot {action} for another user")

If the body changes username or email, the service also re-checks uniqueness.

The UserUpdate schema makes every field optional so clients can send partial updates:

class UserUpdate(BaseModel):
    model_config = ConfigDict(extra="forbid")

    name: Annotated[str | None, Field(min_length=2, max_length=30, default=None)]
    username: Annotated[
        str | None,
        Field(min_length=2, max_length=20, pattern=r"^[a-z0-9]+$", default=None),
    ]
    email: Annotated[EmailStr | None, Field(default=None)]
    profile_image_url: Annotated[
        str | None,
        Field(pattern=r"^(https?|ftp)://[^\s/$.?#].[^\s]*$", default=None),
    ]

Deletion¶

The boilerplate distinguishes three deletion modes — pick based on what the request actually wants.

Soft Delete¶

DELETE /api/v1/users/{username} — sets is_deleted=True and deleted_at=now(). The row stays in the database; the user can no longer log in but their data is preserved.

curl -X DELETE http://localhost:8000/api/v1/users/johndoe \
  -b cookies.txt \
  -H "X-CSRF-Token: <token>"

Permission rules:

• A user can soft-delete their own account
• A superuser can soft-delete anyone

Hard Delete (database)¶

There's no public hard-delete endpoint by design — deleting rows from user would orphan all related data (sessions, API keys, etc.). If you really need it, use FastCRUD's crud_users.db_delete(...) from a script or admin task with full understanding of the foreign-key impact.

GDPR Anonymization¶

DELETE /api/v1/users/db/{username} — superuser only. Replaces PII with neutral values while keeping the row (and therefore foreign-key relationships) intact.

curl -X DELETE http://localhost:8000/api/v1/users/db/johndoe \
  -b superuser_cookies.txt \
  -H "X-CSRF-Token: <token>"

Service implementation:

async def anonymize_user(self, user_id: int, db: AsyncSession) -> None:
    anonymize_data = UserAnonymize(
        name="[DELETED]",
        username=f"del_{user_id}_{timestamp % 10000}",
        hashed_password="DELETED_INVALID_HASH",
        profile_image_url="https://deleted.com/deleted.jpg",
        tier_id=None,
        is_superuser=False,
        google_id=None,
        github_id=None,
        oauth_provider=None,
        email_verified=False,
        oauth_created_at=None,
        oauth_updated_at=None,
    )
    # anonymize the row, then soft-delete it
    await crud_users.update(db=db, object=anonymize_data, commit=False, id=user_id)
    await crud_users.delete(db=db, id=user_id)

Email is intentionally retained for legal compliance purposes (audit trail, "right to be forgotten" doesn't always apply if the platform is required to keep records).

Administrative Operations¶

List All Users¶

GET /api/v1/users/ — superuser only, paginated.

curl "http://localhost:8000/api/v1/users/?page=1&items_per_page=10" \
  -b superuser_cookies.txt

Response shape (via paginated_response):

{
  "data": [
    { "id": 1, "name": "Admin User", "username": "admin", "email": "admin@example.com", ... }
  ],
  "total_count": 42,
  "has_more": true,
  "page": 1,
  "items_per_page": 10
}

See Pagination for the full pattern.

View a User's Tier¶

curl http://localhost:8000/api/v1/users/johndoe/tier -b cookies.txt

Returns the user record joined with their tier. Permission: own profile or superuser.

Change a User's Tier¶

PATCH /api/v1/users/{username}/tier — superuser only.

curl -X PATCH http://localhost:8000/api/v1/users/johndoe/tier \
  -b superuser_cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: <token>" \
  -d '{"tier_id": 2}'

The service verifies the tier exists before assigning it.

View a User's Rate Limits¶

curl http://localhost:8000/api/v1/users/johndoe/rate-limits -b cookies.txt

Returns the rate limits configured for the user's tier. Permission: own profile or superuser.

User Model Reference¶

The actual model lives in modules/user/models.py. Trimmed:

class User(Base, TimestampMixin, SoftDeleteMixin):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(
        "id", autoincrement=True, nullable=False, unique=True,
        primary_key=True, init=False,
    )
    name: Mapped[str] = mapped_column(String(30))
    username: Mapped[str] = mapped_column(String(20), unique=True, index=True)
    email: Mapped[str] = mapped_column(String(50), unique=True, index=True)
    hashed_password: Mapped[str] = mapped_column(String(100))
    profile_image_url: Mapped[str] = mapped_column(
        String, default="https://profileimageurl.com",
    )

    tier_id: Mapped[int | None] = mapped_column(
        Integer, ForeignKey("tiers.id"), index=True, default=None,
    )
    tier: Mapped["Tier | None"] = relationship(
        "Tier", back_populates="users", lazy="selectin", init=False,
    )

    is_superuser: Mapped[bool] = mapped_column(default=False)

    # OAuth (filled when user signs in via Google/GitHub)
    google_id: Mapped[str | None] = mapped_column(String(50), unique=True, index=True, default=None)
    github_id: Mapped[str | None] = mapped_column(String(50), unique=True, index=True, default=None)
    oauth_provider: Mapped[str | None] = mapped_column(String(20), default=None)
    email_verified: Mapped[bool] = mapped_column(default=False)

    @property
    def is_active(self) -> bool:
        # Derived, not stored. is_deleted stays the single source of truth.
        return not self.is_deleted

Mixins from infrastructure/database/models:

• TimestampMixin — created_at, updated_at
• SoftDeleteMixin — is_deleted, deleted_at

The is_active property is derived from not is_deleted — there's no separate column. crudauth reads it during login so a soft-deleted user can't authenticate; is_deleted remains the single source of truth.

Table name is user (singular).

Common CRUD Tasks¶

The same FastCRUD operations described in CRUD Operations work on users:

from src.modules.user.crud import crud_users

# Existence checks
await crud_users.exists(db=db, email="user@example.com")
await crud_users.exists(db=db, username="johndoe")

# Counts
total_active = await crud_users.count(db=db, is_deleted=False)
admin_count = await crud_users.count(db=db, is_superuser=True)

# Filtered queries
result = await crud_users.get_multi(db=db, tier_id=1, is_deleted=False, limit=20)

# Search by username substring
result = await crud_users.get_multi(db=db, username__icontains="ad")

Frontend Integration¶

Use cookies, not bearer tokens. The browser will send the session cookie automatically as long as you set credentials: 'include':

class UserClient {
    constructor(baseUrl = '/api/v1') {
        this.baseUrl = baseUrl;
        this.csrfToken = null;
    }

    async register(userData) {
        const res = await fetch(`${this.baseUrl}/users/`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(userData),
        });
        if (!res.ok) throw new Error((await res.json()).detail);
        return await res.json();
    }

    async login(username, password) {
        const res = await fetch(`${this.baseUrl}/auth/login`, {
            method: 'POST',
            credentials: 'include',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({ username, password }),
        });
        if (!res.ok) throw new Error((await res.json()).detail);
        const { csrf_token } = await res.json();
        this.csrfToken = csrf_token;
        return csrf_token;
    }

    async getProfile() {
        const res = await fetch(`${this.baseUrl}/users/me`, {
            credentials: 'include',
        });
        if (!res.ok) throw new Error('Failed to get profile');
        return await res.json();
    }

    async updateProfile(username, updates) {
        const res = await fetch(`${this.baseUrl}/users/${username}`, {
            method: 'PATCH',
            credentials: 'include',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': this.csrfToken,
            },
            body: JSON.stringify(updates),
        });
        if (!res.ok) throw new Error((await res.json()).detail);
        return await res.json();
    }

    async deleteAccount(username) {
        const res = await fetch(`${this.baseUrl}/users/${username}`, {
            method: 'DELETE',
            credentials: 'include',
            headers: { 'X-CSRF-Token': this.csrfToken },
        });
        if (!res.ok) throw new Error((await res.json()).detail);
        this.csrfToken = null;
        return await res.json();
    }

    async logout() {
        await fetch(`${this.baseUrl}/auth/logout`, {
            method: 'POST',
            credentials: 'include',
            headers: { 'X-CSRF-Token': this.csrfToken },
        });
        this.csrfToken = null;
    }
}

credentials: 'include' makes the browser send/store cookies cross-origin — pair this with CORS_ALLOW_CREDENTIALS=true and an explicit CORS_ORIGINS list (no *) on the server.

Security Considerations¶

Server-side validation¶

All input validation runs server-side via Pydantic schemas. Client-side checks are nice for UX but don't replace server validation.

Login lockout¶

The login endpoint is automatically throttled by crudauth — an escalating per-IP / per-identifier lockout that returns 429 with a Retry-After header. There are no env vars to tune it. See Sessions.

Generic auth error messages¶

POST /api/v1/auth/login returns "Incorrect username or password" for both wrong username and wrong password — never reveal which one was wrong.

Soft delete for accounts¶

The default DELETE /api/v1/users/{username} is a soft delete. Hard deletion only for GDPR-style requests, with anonymization preserving FK integrity.

Next Steps¶

1. Permissions — Role-based access control patterns
2. Sessions — Cookie / CSRF / session lifecycle
3. Production Guide — Hardening checklist