Skip to content

API reference

A concise reference of the public API. Import everything from the submodules; the top-level package exposes no re-exports.

fastapi_simple_tinyauth.models

AuthUser

Frozen dataclass representing the authenticated user.

Fields:

  • username: str — from Remote-User. Required: an AuthUser always represents a logged-in user, so this is never None. Anonymous requests are represented by the absence of a user (request.state.auth_user is None).
  • email: str | None — from Remote-Email.
  • name: str | None — from Remote-Name.
  • groups: tuple[str, ...] — from Remote-Groups (comma-separated).
  • sub: str | None — from Remote-Sub.

Members:

  • has_group(group: str) -> bool
  • has_all_groups(groups: list[str]) -> bool
  • has_any_group(groups: list[str]) -> bool

fastapi_simple_tinyauth.config

TinyauthConfig

Frozen dataclass holding middleware settings.

Constructor arguments:

  • trusted_proxies: list[str] (required) — non-empty list of net/mask or bare IPs. Raises ValueError if empty or unparseable.
  • header_user: str = "Remote-User"
  • header_email: str = "Remote-Email"
  • header_name: str = "Remote-Name"
  • header_groups: str = "Remote-Groups"
  • header_sub: str = "Remote-Sub"

Members:

  • networks: tuple[IPNetwork, ...] — the parsed trusted networks.
  • is_trusted_peer(client_ip: str | None) -> bool

fastapi_simple_tinyauth.middleware

TinyauthMiddleware

Pure-ASGI middleware. Constructed as TinyauthMiddleware(app, config=...) (via app.add_middleware(TinyauthMiddleware, config=config)).

  • build_auth_user(request) -> AuthUser | None — parse headers into an AuthUser, or None when Remote-User is absent.

STATE_ATTR

The attribute name ("auth_user") used on request.state.

fastapi_simple_tinyauth.helpers

  • optional_user(request) -> AuthUser | None
  • require_user(request) -> AuthUser — raises UnauthenticatedError.
  • require_group(group: str) -> Callable[[Request], AuthUser]
  • require_all_groups(groups: list[str]) -> Callable[[Request], AuthUser]
  • require_any_group(groups: list[str]) -> Callable[[Request], AuthUser]

fastapi_simple_tinyauth.exceptions

  • TinyauthError(HTTPException) — base class.
  • UntrustedProxyError — HTTP 403.
  • UnauthenticatedError — HTTP 401.
  • ForbiddenError — HTTP 403.