userharbor-fastapi 0.1.0

Project status: UserHarbor FastAPI is currently in an early stage of development. The API may change frequently. The library is not ready for production use yet.

userharbor-fastapi provides a FastAPI integration for userharbor.

It provides:

• account management routes
• bearer session token authentication
• current-user dependencies
• optional-user dependencies
• role and permission dependencies
• UserHarbor exception to HTTP error mapping
• configurable user serialization

The package only handles FastAPI routing and dependency wiring. It does not store users, send emails, hash passwords, generate tokens, or implement application-specific authentication policy.

Installation

pip install userharbor-fastapi

This package depends on userharbor and FastAPI.

Example usage

from fastapi import Depends, FastAPI
from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI


harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

auth = UserHarborFastAPI(harbor)

app = FastAPI()
app.include_router(auth.router, prefix="/auth", tags=["auth"])


@app.get("/me")
def me(user=Depends(auth.current_user)):
    return user


@app.get("/admin")
def admin(user=Depends(auth.require_role("admin"))):
    return user


@app.get("/billing")
def billing(user=Depends(auth.require_permission("billing.read"))):
    return user

For real applications, configure UserHarbor with a concrete UserStore and EmailSender, such as the official SQLAlchemy and SMTP integrations.

Built-in routes

The adapter exposes account routes through auth.router:

POST   /register
POST   /verify-email
POST   /resend-verification
POST   /login
POST   /logout
POST   /logout-all
GET    /me
POST   /password-reset/request
POST   /password-reset/confirm
POST   /password/change
DELETE /account

Mount the router under the prefix used by your application:

app.include_router(auth.router, prefix="/auth", tags=["auth"])

Authentication

POST /login returns a bearer-compatible token response:

{
  "access_token": "session-token",
  "token_type": "bearer"
}

Send the session token on protected requests:

Authorization: Bearer <session-token>

Dependencies

Use auth.current_user for routes that require a valid session:

@app.get("/account")
def account(user=Depends(auth.current_user)):
    return user

Use auth.optional_user when authentication should be optional:

@app.get("/homepage")
def homepage(user=Depends(auth.optional_user)):
    return {"authenticated": user is not None}

Use role and permission dependencies for authorization:

@app.get("/admin")
def admin(user=Depends(auth.require_role("admin"))):
    return user


@app.get("/invoices")
def invoices(user=Depends(auth.require_permission("billing.invoices.read"))):
    return user

User serialization

By default, /me returns:

{
  "username": "jane",
  "email": "jane@example.com",
  "verified": true
}

Pass user_serializer when your application wants to expose a different public user shape:

auth = UserHarborFastAPI(
    harbor,
    user_serializer=lambda user: {
        "username": user.username,
        "email": user.email,
        "verified": user.verified,
        "display_name": user.display_name,
    },
)

Error responses

UserHarbor exceptions are converted into structured HTTP errors:

{
  "detail": {
    "detail": "Invalid username or password",
    "code": "invalid_credentials"
  }
}

Authentication failures return 401, authorization failures return 403, unknown roles and permissions return 404, validation errors return 400, and username conflicts return 409.

License

UserHarbor FastAPI is released under the MIT License.