Overview

Relevant source files

• .openapi-generator-ignore
• README.md
• openfga_sdk/__init__.py
• pyproject.toml
• uv.lock

The OpenFGA Python SDK is a client library that provides programmatic access to the OpenFGA authorization service. This SDK enables Python applications to perform fine-grained authorization checks, manage relationship tuples, query authorization models, and integrate with OpenFGA's API endpoints.

This document provides a high-level overview of the SDK's architecture, development model, and organization. For detailed information about OpenFGA itself, see What is OpenFGA. For a comprehensive list of SDK capabilities, see SDK Features and Capabilities. For installation and basic usage instructions, see Getting Started.

Sources: README.md1-14 pyproject.toml11-42

Purpose and Scope

This SDK serves as the official Python client for OpenFGA, handling:

• HTTP communication with OpenFGA servers via REST API
• Authentication (API tokens and OAuth2 client credentials flow)
• Request serialization and response deserialization
• Retry logic with exponential backoff for transient failures
• OpenTelemetry integration for observability
• Both asynchronous (async/await) and synchronous execution patterns

The SDK supports Python 3.10, 3.11, and 3.12, and is distributed via PyPI as the openfga-sdk package.

Sources: pyproject.toml22-42 README.md75-119

Layered Architecture

The SDK is organized into four distinct layers, each with specific responsibilities:

Layer Descriptions:

Layer	Primary Classes	Responsibility
High-Level Client	OpenFgaClient, ClientConfiguration	Convenience methods, batch operations, simplified error handling
API Layer	OpenFgaApi, Request/Response models	Direct endpoint access with typed models (generated from OpenAPI)
Transport Layer	ApiClient, OAuth2Client, RESTClientObject	HTTP communication, authentication, retries, serialization
Configuration	Configuration, Credentials, TelemetryConfiguration	Shared configuration for all layers

The high-level client (OpenFgaClient) provides the most ergonomic interface with methods like batch_check(), write_tuples(), and delete_tuples(). The API layer (OpenFgaApi) offers direct access to all API endpoints with full control over request parameters.

Sources: openfga_sdk/__init__.py1-7 README.md122-287

Dual Implementation: Async and Sync

The SDK maintains complete parallel implementations for both asynchronous and synchronous usage patterns:

The async implementation (root openfga_sdk module) uses asyncio and aiohttp for non-blocking I/O. The sync implementation (openfga_sdk.sync submodule) uses threading and urllib3 for blocking calls. Both share the same data models, configuration classes, and exception types.

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

Development Model: Generated and Manual Code

The SDK follows a hybrid development approach:

The .openapi-generator-ignore file specifies which components are manually maintained:

Component	Status	Purpose
OpenFgaApi	Generated	Type-safe API endpoint methods from OpenAPI spec
openfga_sdk.models.*	Generated	Request/response data models
ApiClient	Partially generated	HTTP orchestration, with manual auth extensions
RESTClientObject	Partially generated	Low-level HTTP client
OpenFgaClient	Manual	High-level convenience methods, batch operations
ClientConfiguration	Manual	Client-specific configuration
OAuth2Client	Manual	OAuth2 client credentials flow implementation
Credentials	Manual	Authentication credential management

This hybrid approach allows the SDK to stay synchronized with the OpenFGA API specification while providing ergonomic, Python-idiomatic abstractions.

Sources: .openapi-generator-ignore1-18 README.md12

Key Dependencies

The SDK relies on the following core dependencies:

Dependency	Version	Purpose
aiohttp	≥3.9.3	Async HTTP client for async implementation
urllib3	≥1.26.19, <3	HTTP client for sync implementation
python-dateutil	≥2.9.0	Date/time parsing for API responses
opentelemetry-api	≥1.25.0	Metrics and observability integration

The SDK has no dependencies on the OpenFGA server itself—it communicates exclusively via HTTP REST API.

Sources: pyproject.toml37-42

Entry Points

Applications interact with the SDK through these primary entry points:

For Async Applications:

For Sync Applications:

Both entry points provide access to the full SDK functionality with consistent APIs.

Sources: openfga_sdk/__init__.py1-7 README.md134-287

Common Usage Pattern

A typical SDK usage follows this flow:

The configuration is typically created once at application startup and reused across all requests to benefit from connection pooling and credential caching.

Sources: README.md126-148

Related Documentation

• What is OpenFGA - Overview of OpenFGA as an authorization system
• SDK Features and Capabilities - Detailed list of SDK functionality
• Package Structure - Detailed module organization
• Getting Started - Installation and quick start guide
• Core Architecture - Deep dive into each architectural layer
• Configuration and Authentication - Authentication methods and configuration options

Sources: README.md14-73