Metadata-Version: 2.4
Name: fastapi-betterauth
Version: 0.2.4
Summary: FastAPI helpers for Better Auth JWT verification
Project-URL: Homepage, https://github.com/lukonik/fastapi-betterauth
Project-URL: Repository, https://github.com/lukonik/fastapi-betterauth
Project-URL: Issues, https://github.com/lukonik/fastapi-betterauth/issues
Author: Luka Onikadze
License-Expression: MIT
License-File: LICENSE
Keywords: auth,better-auth,fastapi,jwks,jwt
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pyjwt[crypto]>=2.12.1
Requires-Dist: typing-extensions>=4.5
Provides-Extra: dev
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: uvicorn>=0.30; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Description-Content-Type: text/markdown

# fastapi-betterauth

FastAPI helpers for Better Auth JWT verification.

The package verifies Better Auth JWTs with PyJWT and JWKS, then exposes the
verified claims either through a plain Python verifier or a FastAPI dependency.

## Installation

```bash
pip install fastapi-betterauth
```

For FastAPI dependency helpers:

```bash
pip install "fastapi-betterauth[fastapi]"
```

## Usage

```python
from fastapi_betterauth import BetterAuthVerifier

verifier = BetterAuthVerifier("https://your-app.example.com")

claims = verifier.validate_token(token)
```

By default, the verifier:

- reads keys from `/api/auth/jwks`
- verifies the `EdDSA` algorithm
- expects `iss` to match `base_url`
- expects `aud` to match `base_url`

## FastAPI

```python
from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi_betterauth import BetterAuthVerifier

app = FastAPI()
verifier = BetterAuthVerifier("https://your-app.example.com")
current_user = verifier.fastapi_dependency()


@app.get("/me")
def me(claims: Annotated[dict, Depends(current_user)]):
    return claims
```

Invalid tokens are converted to `401 Unauthorized` responses.

## Configuration

```python
from fastapi_betterauth import BetterAuthVerifier

verifier = BetterAuthVerifier(
    "https://your-app.example.com",
    jwks_path="/api/auth/jwks",
    issuer="https://your-app.example.com",
    audience="https://your-app.example.com",
    algorithms=("EdDSA",),
    cache_jwk_set=True,
    lifespan=300,
)
```

Set `issuer=None` or `audience=None` to disable that specific validation.

## Compatibility API

The older module-level style is still available:

```python
from fastapi_betterauth import init_client, validate_token

init_client("https://your-app.example.com")
claims = validate_token(token)
```

Prefer `BetterAuthVerifier` for new code because it avoids global state and
works better for tests, multiple apps, and multi-tenant services.

## FastAPI demo server

This repository includes a small FastAPI demo in `examples/fastapi_demo.py`.
Use it to test a real bearer token issued by your Better Auth application.

```bash
BETTER_AUTH_BASE_URL="http://localhost:3000" uv run python -m uvicorn examples.fastapi_demo:app --reload
```

The demo reads JWKS from `${BETTER_AUTH_BASE_URL}/api/auth/jwks` by default.
Override that path with `BETTER_AUTH_JWKS_PATH` if your Better Auth app uses a
different route.

Public route:

```bash
curl http://localhost:8000/public
```

Protected route:

```bash
curl \
  -H "Authorization: Bearer $BETTER_AUTH_TOKEN" \
  http://localhost:8000/me
```
