Overview

Relevant source files

• README.md
• openfga_sdk/__init__.py
• pyproject.toml
• uv.lock

This document provides a high-level introduction to the OpenFGA Python SDK, its architecture, and capabilities. The SDK is a wrapper around the OpenFGA API that provides both synchronous and asynchronous clients for integrating fine-grained authorization into Python applications.

For detailed information about OpenFGA concepts and terminology, see What is OpenFGA. For comprehensive feature documentation, see SDK Features and Capabilities. For details on how code is organized, see Package Structure.

What is the OpenFGA Python SDK?

The OpenFGA Python SDK is an autogenerated client library that wraps the OpenFGA API, providing a convenient interface for managing authorization in Python applications. OpenFGA is an open-source Fine-Grained Authorization solution inspired by Google's Zanzibar paper, designed to make it easy for application builders to model their permission layer and integrate authorization checks.

The SDK provides:

• High-level convenience methods through the OpenFgaClient class for common operations
• Direct API access through the generated OpenFgaApi class for advanced use cases
• Dual execution models with complete async/await and synchronous implementations
• Built-in retry logic with exponential backoff for transient failures
• OAuth2 token management with automatic refresh and caching
• OpenTelemetry integration for observability and metrics
• Batch operations for efficient bulk authorization checks

Sources: README.md1-122 README.md59-64 pyproject.toml12-14

SDK Architecture Layers

The SDK follows a layered architecture with clear separation of concerns, from high-level convenience methods down to HTTP transport:

Layer Responsibilities:

Layer	Components	Responsibility
High-Level Client	OpenFgaClient, ClientConfiguration	User-facing convenience methods, parameter transformation, batch operations
Generated API	OpenFgaApi, model classes	Direct 1:1 mapping to OpenFGA API endpoints from OpenAPI specification
Core Infrastructure	ApiClient, Configuration, OAuth2Client, Credentials	HTTP orchestration, authentication, retry logic, configuration management
Transport	RESTClientObject, telemetry	Low-level HTTP operations, observability

Sources: openfga_sdk/__init__.py1-14 README.md122-148

Key SDK Components

OpenFgaClient

The OpenFgaClient class provides the primary interface for SDK users. It wraps the lower-level OpenFgaApi and adds convenience features:

• Parameter transformation: Converts client-friendly models to API request formats
• Default values: Applies store ID and authorization model ID from configuration
• Batch operations: batch_check, client_batch_check with parallel execution
• Streaming support: streamed_list_objects for handling large result sets
• Error enrichment: Adds operation context to exceptions

Available in two variants:

• Async: openfga_sdk.client.OpenFgaClient with async/await methods
• Sync: openfga_sdk.sync.client.OpenFgaClient with blocking methods

Sources: README.md122-148 openfga_sdk/__init__.py3-4

OpenFgaApi

The OpenFgaApi class is autogenerated from the OpenAPI specification and provides direct access to all API endpoints. Each API operation has a corresponding method:

• check(), batch_check() - Authorization checks
• list_objects(), streamed_list_objects() - List accessible objects
• read(), write() - Relationship tuple operations
• write_authorization_model(), read_authorization_model() - Model management
• create_store(), list_stores(), get_store(), delete_store() - Store operations

Sources: README.md1314-1339 openfga_sdk/__init__.py1

ApiClient

The ApiClient class orchestrates HTTP requests and implements cross-cutting concerns:

• Request serialization: Converts Python objects to JSON
• Response deserialization: Parses JSON to model instances
• Authentication: Integrates with OAuth2Client for credential handling
• Retry logic: Exponential backoff with jitter for 429 and 5xx errors
• Telemetry: Records request metrics via OpenTelemetry
• Header management: Applies default and per-request headers

Sources: README.md1264-1287 openfga_sdk/__init__.py2

Configuration Classes

Two configuration classes manage SDK settings at different levels:

ClientConfiguration (openfga_sdk.client.configuration):

• api_url - OpenFGA server URL
• store_id - Default store identifier
• authorization_model_id - Default authorization model
• credentials - Authentication configuration
• headers - Default request headers

Configuration (openfga_sdk.configuration):

• api_url, host, scheme - Server connection settings
• ssl_ca_cert - SSL certificate path
• timeout - Request timeout in milliseconds
• retry_params - Retry behavior configuration
• telemetry - Observability settings

Sources: README.md134-230 openfga_sdk/__init__.py4-5

Dual Execution Model: Async and Sync

The SDK provides complete parallel implementations for asynchronous and synchronous execution:

Key Differences:

Aspect	Async (openfga_sdk.*)	Sync (openfga_sdk.sync.*)
Method Signature	async def method_name()	def method_name()
Usage	await client.check(...)	client.check(...)
HTTP Library	aiohttp	urllib3
Concurrency	Non-blocking I/O with asyncio	Blocking I/O
Best For	High-concurrency applications, web frameworks (FastAPI, aiohttp)	Traditional applications, scripts, Django

Both implementations share the same data models, configuration classes, and telemetry infrastructure, ensuring API consistency.

Sources: README.md266-287 pyproject.toml37-42

Request Flow Example

The following diagram illustrates how a typical authorization check flows through the SDK layers:

Sources: README.md796-826 README.md1264-1287

Installation and Basic Usage

Installation

The SDK is available via PyPI and requires Python 3.10 or higher:

Dependencies:

• aiohttp>=3.9.3 - Async HTTP client
• urllib3>=1.26.19,<3 - Sync HTTP client
• python-dateutil>=2.9.0 - Date/time utilities
• opentelemetry-api>=1.25.0 - Telemetry integration

Sources: README.md75-120 pyproject.toml35-42

Basic Usage Example

Async Client:

Sync Client:

Sources: README.md122-204 README.md266-287

Generated vs Custom Code

The SDK architecture separates generated code from custom enhancements:

Generated Code provides:

• Direct API endpoint mappings from OpenAPI spec
• Request/response model classes
• Basic HTTP client infrastructure
• Standard exception types

Custom Code adds:

• High-level convenience methods (OpenFgaClient)
• Batch operations and streaming
• OAuth2 token management with caching
• OpenTelemetry integration
• Dual async/sync implementations
• Enhanced error handling

The .openapi-generator-ignore file ensures generated code is excluded from version control and regenerated during builds.

Sources: README.md12 openfga_sdk/__init__.py1-14

Core API Operations

The SDK provides methods for all OpenFGA operations, organized into functional categories:

Category	Operations	Description
Store Management	create_store, get_store, list_stores, delete_store	Manage authorization stores (containers for models and tuples)
Authorization Models	write_authorization_model, read_authorization_model, read_latest_authorization_model, read_authorization_models	Define and retrieve permission schemas
Relationship Tuples	write, read, read_changes, write_tuples, delete_tuples	Manage relationship data (who has what relation to which object)
Authorization Queries	check, batch_check, expand, list_objects, list_relations, list_users	Perform authorization checks and queries
Streaming	streamed_list_objects	Handle large result sets efficiently
Assertions	read_assertions, write_assertions	Test authorization models

For detailed documentation on each operation, see API Operations.

Sources: README.md296-1262 openfga_sdk/__init__.py15-131

Key Features

Automatic Retry with Exponential Backoff

The SDK automatically retries failed requests with 429 (rate limit) or 5xx (server error) status codes:

• Default: Up to 3 retries with minimum 100ms wait between attempts
• Configurable: RetryParams allows customization up to 15 retries
• Intelligent backoff: Exponential backoff with jitter, respects Retry-After headers
• Max wait: Configurable maximum wait time between retries

Sources: README.md1264-1287

OpenTelemetry Integration

Built-in observability with OpenTelemetry metrics:

• Counters: Request counts by endpoint, method, and status
• Histograms: Request duration distributions
• Attributes: Store ID, model ID, custom attributes
• Configurable: Filter attributes, customize metric names

For details, see Telemetry and Observability.

Sources: pyproject.toml40 openfga_sdk/__init__.py125-131

Batch Operations

Efficient bulk authorization checks:

• batch_check: Server-side batch checking (OpenFGA 1.8.0+)
• client_batch_check: Client-side parallel checking for older servers
• Transaction modes: Optional non-transactional writes with chunking
• Parallel execution: Configurable concurrency limits

For examples, see Batch Operations.

Sources: README.md828-1035

Authentication Methods

Supports multiple authentication approaches:

• None: No authentication (development/testing)
• API Token: Static bearer token
• Client Credentials: OAuth2 client credentials flow with automatic token refresh

For configuration details, see Credentials and Authentication Methods.

Sources: README.md132-204

Next Steps

To get started with the SDK:

1. Installation and Dependencies - Set up your environment
2. Quick Start Guide - Run your first authorization check
3. Configuration Basics - Configure the client for your environment
4. Core Architecture - Understand the SDK's internal structure
5. API Operations - Explore available operations and their usage

For specific use cases:

• Authorization checks: See Authorization Checks
• Managing relationships: See Relationship Tuples
• Batch operations: See Batch Operations
• Error handling: See Exception Reference

Sources: README.md14-57