Skip to content

FastAPI-Topaz

Authorization framework for FastAPI using Topaz.

Add fine-grained authorization to your FastAPI application with native dependency injection, caching, circuit breakers, and observability built in.

flowchart LR
    subgraph Your App
        F[FastAPI<br/>Endpoints]
    end

    subgraph fastapi-topaz
        D[Dependencies<br/>or Middleware]
        C[Cache]
        CB[Circuit<br/>Breaker]
    end

    subgraph Topaz
        A[Authorizer<br/>Rego Policies]
        DS[Directory<br/>Relationships]
    end

    F --> D
    D <--> C
    D <--> CB
    CB --> A
    A <--> DS

    style D fill:#6366f1,color:#fff
    style C fill:#818cf8,color:#fff
    style CB fill:#818cf8,color:#fff

Quick Start

from fastapi import Depends, FastAPI, Request
from fastapi_topaz import (
    AuthorizerOptions,
    Identity,
    IdentityType,
    TopazConfig,
    require_rebac_allowed,
)

config = TopazConfig(
    authorizer_options=AuthorizerOptions(url="localhost:8282"),
    policy_path_root="myapp",
    identity_provider=lambda r: Identity(
        type=IdentityType.IDENTITY_TYPE_SUB, value=r.state.user_id
    ),
    policy_instance_name="myapp",
)

app = FastAPI()

@app.get("/documents/{id}")
async def get_document(
    id: int,
    request: Request,
    _: None = Depends(require_rebac_allowed(config, "document", "can_read")),
):
    return {"id": id, "title": "My Document"}

Installation

pip install fastapi-topaz

Features

  • RBAC, ABAC & ReBAC

    Support for all authorization models: role-based, attribute-based, and relationship-based. Combine them in a single Rego policy for fine-grained control.

  • Dependencies & Middleware

    Native FastAPI integration via Depends() or global TopazMiddleware. Auto-generate policy paths or specify them explicitly.

  • Decision Caching

    TTL-based caching reduces Topaz calls by 90%+. Configurable per policy path with automatic invalidation.

  • Circuit Breaker

    Graceful degradation when Topaz is unavailable. Serve stale cache, fail-open, or fail-closed.

  • Observability

    Prometheus metrics and OpenTelemetry tracing. Monitor latency, cache hit rates, and circuit state.

  • Audit Logging

    Structured JSON logs for every authorization decision. Compliance-ready with request correlation.

Start Here

  • New to fastapi-topaz?

    Start with the Getting Started tutorial to add authorization in 15 minutes.

    Getting Started

  • Want a complete example?

    Follow the Example App tutorials with real OIDC and database setup.

    Example App

  • Already using it?

    Check the How-to Guides for specific tasks and the API Reference.

    How-to Guides

Documentation Structure

This documentation follows the Diataxis framework:

Section Purpose Start Here
Tutorials Learning-oriented, step-by-step guides Getting Started
How-to Guides Task-oriented, solve specific problems Identity Providers
Reference Technical specifications API Reference
Explanation Understanding-oriented, concepts Architecture

Feature Status

Feature Status Documentation
Policy-based authorization ✅ Stable API Reference
ReBAC (relationship-based) ✅ Stable API Reference
Auto policy path resolution ✅ Stable API Reference
Decision caching ✅ Stable API Reference
Circuit breaker ✅ Stable Circuit Breaker
Connection pooling ✅ Stable Connection Pooling
Authorization middleware ✅ Stable Middleware
Audit logging ✅ Stable Audit Logging
Prometheus metrics ✅ Stable Observability
OpenTelemetry tracing ✅ Stable Observability
Testing utilities ✅ Stable Testing
CLI tools ✅ Stable CLI Reference
Resource hierarchy ✅ Stable Resource Hierarchy
Integration testing ✅ Stable Integration Testing

Requirements

  • Python 3.9+
  • FastAPI 0.100+
  • Running Topaz instance

External Resources