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.