Overview

Relevant source files

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

This document provides a comprehensive introduction to the OpenFGA Python SDK, covering its purpose, architecture philosophy, and relationship to the OpenFGA authorization service. It explains the SDK's layered design, dual execution model (async/sync), and key components that applications interact with.

For installation instructions and quick start examples, see Getting Started. For detailed API operation documentation, see API Operations. For configuration options, see Configuration and Authentication.

---

What is the OpenFGA Python SDK

The OpenFGA Python SDK is a client library that provides programmatic access to the OpenFGA authorization service. It is primarily auto-generated from the OpenFGA API specification using OpenAPI Generator, with hand-written high-level client wrappers and utilities added on top for developer convenience.

The SDK serves as a bridge between Python applications and OpenFGA servers, handling:

• HTTP communication and connection pooling
• Authentication (API tokens, OAuth2 client credentials)
• Request serialization and response deserialization
• Automatic retry logic for transient failures
• Telemetry and observability via OpenTelemetry

Key characteristics:

• Supports Python 3.10, 3.11, and 3.12
• Dual execution models: fully asynchronous (using asyncio and aiohttp) and synchronous (using urllib3)
• Published to PyPI as openfga-sdk
• Apache 2.0 licensed

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

---

Architecture Philosophy

The SDK follows a layered architecture with clear separation of concerns. Each layer has a specific responsibility and delegates downward through the stack:

Layered Design

Layer responsibilities:

Layer	Primary Classes	Responsibility
High-Level Client	OpenFgaClient, ClientConfiguration	Convenience methods, batch operations, streaming, client-side logic
Direct API	OpenFgaApi, Model classes	One-to-one mappings to OpenFGA API endpoints
HTTP Orchestration	ApiClient, Configuration, OAuth2Client	Request preparation, authentication, retry logic, telemetry
Transport	RESTClientObject	Raw HTTP communication using aiohttp (async) or urllib3 (sync)

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

---

Dual Execution Model

The SDK provides complete parallel implementations for asynchronous and synchronous execution. This allows applications to choose their concurrency model based on their runtime environment and performance requirements.

Key points:

• Async path: Uses async/await syntax, asyncio, and aiohttp for I/O
• Sync path: Uses blocking calls and urllib3 for I/O
• Shared components: Data models, configuration, exceptions, validation, and telemetry are identical across both paths
• API surface: Both paths expose the same methods and parameters, differing only in async/await keywords

Sources: README.md266-287 openfga_sdk/__init__.py1-6

---

Package Structure

The openfga_sdk package is organized into distinct modules based on functionality:

Module breakdown:

Module	Purpose	Key Files
client/	High-level client wrapper	client.py, configuration.py
api/	Direct API endpoint methods	open_fga_api.py
api_client.py	HTTP orchestration	Single file with ApiClient class
configuration.py	Low-level configuration	Single file with Configuration, RetryParams
rest.py	HTTP transport	Single file with RESTClientObject
models/	Auto-generated data models	100+ individual model files
credentials/	Authentication	oauth2_client.py, credentials.py, config.py
telemetry/	Observability	metrics.py, attributes.py, configuration.py
exceptions.py	Error hierarchy	ApiException, FgaValidationException, etc.
validation.py	Input validation	ULID validation, parameter checks
sync/	Synchronous mirror	Complete parallel implementation

Auto-generated vs. hand-written:

• Auto-generated: api/, models/, parts of api_client.py and rest.py
• Hand-written: client/, credentials/, telemetry/, validation.py, exceptions.py

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

---

Key Components

OpenFgaClient

The primary entry point for most applications. Located in openfga_sdk.client.client (async) and openfga_sdk.sync.client (sync).

Responsibilities:

• Provides user-friendly method signatures
• Implements client-side batch operations (client_batch_check, batch_check)
• Implements streaming operations (streamed_list_objects)
• Implements high-level queries (list_relations)
• Manages ClientConfiguration (store ID, authorization model ID)
• Delegates to OpenFgaApi for actual API calls

Usage pattern:

Sources: README.md134-149 openfga_sdk/__init__.py3

---

OpenFgaApi

The direct API interface with one-to-one endpoint mappings. Located in openfga_sdk.api.open_fga_api (async) and openfga_sdk.sync.api (sync).

Responsibilities:

• Maps to OpenFGA API endpoints exactly as defined in the OpenAPI specification
• No client-side logic or conveniences
• Accepts raw request models and returns raw response models
• Used by OpenFgaClient internally, but can also be used directly for fine-grained control

Available methods: check, batch_check, expand, list_objects, read, write, create_store, delete_store, get_store, list_stores, read_authorization_models, read_authorization_model, write_authorization_model, read_assertions, write_assertions, read_changes, list_users, and streamed_list_objects.

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

---

ApiClient

The HTTP orchestration engine. Located in openfga_sdk.api_client (async) and openfga_sdk.sync.api_client (sync).

Responsibilities:

• Prepares HTTP requests (method, URL, headers, body)
• Serializes request objects to JSON
• Deserializes response JSON to model objects
• Manages authentication (delegates to OAuth2Client for OAuth2 flows)
• Implements retry logic with exponential backoff for 429 and 5xx errors
• Records telemetry metrics via TelemetryMetrics
• Manages the RESTClientObject for actual HTTP I/O

Sources: openfga_sdk/__init__.py2

---

Configuration and ClientConfiguration

Two configuration classes with different scopes:

Configuration (openfga_sdk.configuration):

• Low-level HTTP and SDK settings
• Properties: host, access_token, api_key, api_key_prefix, username, password, discard_unknown_keys, disabled_client_side_validations, server_index, server_variables, server_operation_index, server_operation_variables, ssl_ca_cert, cert_file, key_file, verify_ssl, proxy, proxy_headers, safe_chars_for_path_param, retries
• Manages RetryParams (max_retry, min_wait_in_ms)
• Manages TelemetryConfiguration

ClientConfiguration (openfga_sdk.client.configuration):

• High-level client settings
• Properties: api_url, store_id, authorization_model_id, credentials, retry_params, telemetry, headers
• Used by OpenFgaClient
• Builds Configuration internally

Sources: README.md139-148 README.md1272-1287 openfga_sdk/__init__.py4-5

---

Data Models

Over 100 auto-generated model classes in openfga_sdk.models, representing API request and response structures.

Core models:

• TupleKey: Represents a relationship tuple (user, relation, object)
• Store: A logical container for authorization data
• AuthorizationModel: Schema defining types and relations
• CheckRequest, CheckResponse: Authorization check operation
• WriteRequest: Tuple write/delete operations
• ReadRequest, ReadResponse: Tuple read operations
• ListObjectsRequest, ListObjectsResponse: List accessible objects

All models support:

• Validation on instantiation
• JSON serialization/deserialization
• Type hints for IDE support
• to_dict() and to_str() methods

Sources: openfga_sdk/__init__.py15-124 README.md52

---

How Authorization Checks Flow Through the SDK

This diagram illustrates a typical check operation's path through the SDK layers, showing how application code interacts with OpenFGA:

Key observations:

1. OpenFgaClient adds convenience (auto-applies store_id, model_id)
2. OpenFgaApi translates to raw API calls
3. ApiClient handles cross-cutting concerns (auth, retries, telemetry)
4. OAuth2 tokens are cached and reused until expiry
5. Retries use exponential backoff with jitter to avoid thundering herds
6. Telemetry is recorded automatically for all operations

Sources: README.md803-825 README.md1264-1311

---

SDK Dependencies

The SDK has minimal required dependencies to reduce supply chain risk and simplify installation:

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

Development dependencies: pytest, pytest-asyncio, pytest-cov, ruff, mypy, mock, griffe

Sources: pyproject.toml37-55

---

Relationship to OpenFGA Service

The SDK is a client library that communicates with an OpenFGA server instance over HTTP. It does not implement authorization logic itself—it delegates all authorization decisions to the OpenFGA service.

OpenFGA service responsibilities:

• Store and version authorization models
• Store relationship tuples
• Evaluate authorization checks using models and tuples
• Execute complex queries (expand, list_objects, list_users)

SDK responsibilities:

• Provide a Pythonic API to OpenFGA's HTTP endpoints
• Handle authentication, retries, connection pooling
• Provide client-side conveniences (batching, streaming)
• Integrate with Python observability tools (OpenTelemetry)

Sources: README.md59-64

---

Feature Highlights

The SDK provides a comprehensive feature set for integrating OpenFGA into Python applications:

Feature	Description	Page Reference
Async/Sync Support	Complete dual implementation	Async vs Sync Implementations
Store Management	Create, read, update, delete stores	Store Management
Authorization Models	Versioned schema management	Authorization Models
Tuple Operations	Write, read, delete relationship tuples	Relationship Tuples
Check Operations	Single and batch authorization checks	Authorization Checks
Advanced Queries	Expand, list_objects, list_users, list_relations	Advanced Queries
Batch Operations	Client-side and server-side batching	Batch Operations
Streaming	Incremental result processing for large datasets	Streaming Operations
Contextual Tuples	Temporary relationships for checks	Contextual Tuples and Conditions
Conditions	Attribute-based access control	Contextual Tuples and Conditions
Authentication	API token and OAuth2 client credentials	Credentials and Authentication Methods
Automatic Retries	Exponential backoff for 429/5xx errors	Retry Logic and Error Handling
Telemetry	OpenTelemetry metrics integration	Telemetry and Observability
Conflict Options	Idempotent writes (OpenFGA v1.10.0+)	ConflictOptions for Write Operations

Sources: README.md14-52

---

Version and Compatibility

Current version: 0.9.9 (as of this documentation)

Python version requirements: 3.10, 3.11, 3.12

OpenFGA server compatibility: The SDK is designed to work with OpenFGA 1.x servers. Some features require specific server versions:

• Batch Check: Requires OpenFGA 1.8.0+
• Conflict Options: Requires OpenFGA 1.10.0+

For detailed version compatibility information, see OpenFGA Server Version Compatibility.

Sources: pyproject.toml13 pyproject.toml23-25 pyproject.toml35 README.md830-831 README.md754

---

This overview establishes the foundation for understanding the OpenFGA Python SDK. For hands-on guidance, proceed to Getting Started. For deep dives into specific subsystems, consult the relevant sections in the table of contents.