Access402 FastAPI adapter

This package protects FastAPI routes with Access402's managed x402 v2 payment service. Route shapes and OpenAPI schemas come from the running application; pricing, enablement, sandbox/live mode, reusable access, and discovery remain dashboard settings.

Install locally

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

Connect an application

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

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.

Define routes first, then install Access402:

from fastapi import FastAPI
from access402_fastapi import Access402

app = FastAPI()

@app.get("/reports/{report_id}")
async def report(report_id: str):
    return {"id": report_id, "result": "..."}

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

On its first request, the adapter authenticates the installation, uploads a compact route catalog, and downloads an 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.

After the first catalog sync, open the installation's Manage API routes screen in the dashboard to choose routes, prices, access policies, environment, and Bazaar publication.

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

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:

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

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