Metadata-Version: 2.4
Name: access402-fastapi
Version: 0.2.0
Summary: Managed Access402 x402 v2 protection for FastAPI
Project-URL: Homepage, https://access402.com
Project-URL: Documentation, https://access402.com/docs/fastapi/get-started
Project-URL: Repository, https://github.com/JonathanRoyere/Access402Dash
Project-URL: Issues, https://github.com/JonathanRoyere/Access402Dash/issues
Author: Jonathan Royere
Keywords: access402,api-monetization,fastapi,payments,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.8
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8.3; extra == 'test'
Requires-Dist: uvicorn>=0.30; extra == 'test'
Description-Content-Type: text/markdown

# Access402 FastAPI adapter

This package protects explicitly declared FastAPI routes with Access402's managed x402 v2 payment service. Routes, USDC prices, access policy, descriptions, and discovery intent live beside the endpoint in Python. Access402 provides signed configuration, x402 challenges, hosted verification and settlement, plan enforcement, discovery publication, and activity logs.

## Install locally

```bash
pip install -e "./adapters/fastapi[test]"
```

## Connect an application

Create a **FastAPI** installation in the Access402 dashboard, then configure server-only environment variables:

```bash
ACCESS402_INSTALLATION_ID=your-installation-uuid
ACCESS402_API_KEY=your-installation-key
ACCESS402_PUBLIC_BASE_URL=https://api.example.com
ACCESS402_ALLOW_LIVE=false
```

The API key belongs only in the FastAPI server environment. Never expose it in browser code, logs, OpenAPI documents, or a committed `.env` file. `ACCESS402_API_BASE_URL` is intentionally optional and should only be overridden for local Access402 backend development.

Create the Access402 manager before declaring paid routes, then install it after all routes:

```python
from fastapi import FastAPI
from access402_fastapi import Access402

app = FastAPI()
access402 = Access402.from_env()

@app.get("/reports/{report_id}")
@access402.protect(
    price="0.05",
    access_type="per_request",
    description="Read one premium report",
)
async def report(report_id: str):
    return {"id": report_id, "result": "..."}

access402.install(app)
```

On startup, the adapter authenticates the installation, uploads only decorated payment policies, and downloads HMAC-authenticated configuration. The configuration is cached in memory and refreshed periodically; payment requests go directly to the Access402 settlement function. No CDP credential is installed in this package.

The dashboard displays a read-only mirror of code-owned policies. It controls the installation payment environment, while protected routes fail closed if Access402 cannot confirm a matching server-side policy.

Dynamic path routes such as `/reports/{report_id}` can be protected. Discovery publication for those routes stays disabled until Access402 supports a concrete path-parameter example; publishing a literal template URL would create a broken Bazaar entry.

`ACCESS402_PUBLIC_BASE_URL` remains required. It is the trusted canonical origin placed in x402 resource URLs and validated against the installation's authorized origins. Inferring it from an incoming `Host` or forwarding header would allow a spoofed request to alter payment and discovery metadata. Use a separate FastAPI installation for local, staging, and production deployments; replicas of the same deployment may share one installation.

Live mode requires both the dashboard toggle and `ACCESS402_ALLOW_LIVE=true`. This second switch is a deployment safety ceiling, not another credential.

The adapter answers its own 402 responses with `Access-Control-Allow-Origin: *` by default so agent and browser clients can read the payment challenge. Set `ACCESS402_CORS_ALLOW_ORIGIN` to the API's exact browser origin when credentials are involved. CORS preflight (`OPTIONS`) is never paywalled.

## Bypasses

There is no header-based administrator bypass. If an application needs trusted internal access, pass a callback that validates the application's real authentication state:

```python
async def trusted_internal_request(scope):
    user = scope.get("state", {}).get("user")
    return bool(user and user.is_admin)

access402 = Access402.from_env(bypass=trusted_internal_request)
```

Put authentication middleware outside Access402 if the callback depends on middleware-populated state. A spoofable header must never be used as the bypass decision.

## Tests

```bash
cd adapters/fastapi
python -m pip install -e ".[test]"
pytest
```
