Overview

Relevant source files

Purpose and Scope

This document provides a comprehensive introduction to the OpenFGA Python SDK, explaining its architecture, core components, and relationship to the OpenFGA authorization service. It covers the SDK's layered design, dual execution models (async/sync), authentication mechanisms, and key abstractions that enable Python applications to integrate with OpenFGA.

For installation and configuration details, see Getting Started. For in-depth API operation documentation, see API Operations. For authentication configuration specifics, see Configuration and Authentication.

Sources: README.md1-58 openfga_sdk/__init__.py1-242

What is OpenFGA

OpenFGA is an open-source fine-grained authorization service inspired by Google's Zanzibar paper. It provides relationship-based access control (ReBAC) where permissions are derived from relationships between users, objects, and groups. The authorization model is defined using type definitions and relations, allowing developers to express complex permission rules declaratively.

This Python SDK provides programmatic access to the OpenFGA API, enabling Python applications to:

Manage authorization models (schema definitions)
Write and query relationship tuples (the authorization data)
Perform authorization checks
Execute advanced relationship queries (expand, list_objects, list_users)

The SDK is auto-generated from the OpenFGA OpenAPI specification with hand-written convenience methods and client-side batching logic.

Sources: README.md59-64 pyproject.toml12-42

SDK Architecture and Core Components

The SDK implements a layered architecture with clear separation of concerns:

Key Components:

Layer	Component	Module Path	Purpose
Client	`OpenFgaClient`	`openfga_sdk.client.client`	High-level wrapper with convenience methods, batch operations, contextual tuples
Client	`ClientConfiguration`	`openfga_sdk.client.configuration`	Client-specific settings: `store_id`, `authorization_model_id`, custom headers
API	`OpenFgaApi`	`openfga_sdk.api.open_fga_api`	Direct 1:1 mapping to OpenFGA REST API endpoints
Infrastructure	`ApiClient`	`openfga_sdk.api_client`	Request orchestration, parameter serialization, retry logic, telemetry integration
Infrastructure	`Configuration`	`openfga_sdk.configuration`	SDK-wide settings: `api_url`, `retry_params`, `ssl_ca_cert`, `timeout_millisec`
Infrastructure	`OAuth2Client`	`openfga_sdk.oauth2`	OAuth2 client credentials flow, token caching, automatic refresh
Infrastructure	`Credentials`	`openfga_sdk.credentials`	Authentication method and configuration (`none`, `api_token`, `client_credentials`)
Transport	`RESTClientObject`	`openfga_sdk.rest` / `openfga_sdk.sync.rest`	Low-level HTTP client (aiohttp for async, urllib3 for sync)
Data	Model classes	`openfga_sdk.models.*`	200+ generated Pydantic-like models for requests/responses

Sources: openfga_sdk/__init__.py1-14 README.md122-287 Diagram 1 from architecture diagrams

Request Execution Flow

The following diagram illustrates how a typical API request flows through the SDK layers, showing the actual methods and classes involved:

Sources: openfga_sdk/api_client.py1-600 (inferred from architecture), openfga_sdk/client/client.py1-500 (inferred), Diagram 3 from architecture diagrams

Dual Execution Model: Async vs Sync

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

Module Organization:

Execution Model	Import Path	Use Case
Async	`from openfga_sdk import OpenFgaClient, OpenFgaApi`	FastAPI, aiohttp servers, concurrent workloads
Sync	`from openfga_sdk.sync import OpenFgaClient, OpenFgaApi`	Scripts, CLI tools, simple integrations

Both execution paths share:

Configuration classes (Configuration, ClientConfiguration, Credentials)
All data models (openfga_sdk.models.*)
Exception classes (openfga_sdk.exceptions)
Business logic (validation, telemetry)

Only the HTTP transport layer differs: aiohttp.ClientSession for async, urllib3.PoolManager for sync.

Sources: README.md266-287 openfga_sdk/sync/rest.py1-100 (inferred), Diagram 2 from architecture diagrams

Package Structure

The SDK is organized into the following modules:

Key Modules:

Module Path	Purpose	Generated/Hand-Written
`openfga_sdk/__init__.py`	Public API surface, exports all user-facing classes	Hand-written
`openfga_sdk/client/`	High-level client with convenience methods	Hand-written
`openfga_sdk/api/open_fga_api.py`	Direct API endpoint mappings	Generated
`openfga_sdk/api_client.py`	HTTP orchestration, retry, telemetry	Generated with modifications
`openfga_sdk/configuration.py`	SDK configuration classes	Generated with modifications
`openfga_sdk/credentials.py`	Authentication configuration	Hand-written
`openfga_sdk/oauth2.py`	OAuth2 client implementation	Hand-written
`openfga_sdk/rest.py`	Async HTTP transport	Generated with modifications
`openfga_sdk/sync/rest.py`	Sync HTTP transport	Hand-written
`openfga_sdk/models/`	Request/response data models	Generated
`openfga_sdk/telemetry/`	OpenTelemetry integration	Hand-written
`openfga_sdk/exceptions.py`	Exception hierarchy	Generated with additions

Sources: openfga_sdk/__init__.py1-242 README.md1-58 pyproject.toml1-152

SDK Capabilities

The SDK provides comprehensive functionality for interacting with OpenFGA:

Store Management:

list_stores(), create_store(), get_store(), delete_store()

Authorization Model Management:

write_authorization_model(), read_authorization_models(), read_authorization_model(), read_latest_authorization_model()

Relationship Tuple Operations:

write() - Create/delete tuples (transaction and non-transaction modes)
read() - Query stored tuples
read_changes() - Watch tuple changes

Authorization Checks:

check() - Single authorization check
batch_check() - Server-side batching (OpenFGA v1.8.2+)
client_batch_check() - Client-side parallel checks

Advanced Queries:

expand() - Visualize userset tree
list_objects() - Objects user can access
streamed_list_objects() - Streaming variant
list_relations() - Relations user has on object
list_users() - Users with relation to object

Assertions:

read_assertions(), write_assertions() - Test case management

Cross-Cutting Features:

Automatic retry with exponential backoff and jitter
OpenTelemetry metrics integration
OAuth2 client credentials flow with token caching
Contextual tuples for request-scoped relationships
Consistency preferences for read operations
Conflict handling options for writes (v1.10.0+)

Sources: README.md296-1262 Diagram 4 from architecture diagrams

Version Compatibility

Python Requirements:

Python 3.10, 3.11, or 3.12

Key Dependencies:

aiohttp >= 3.9.3 - Async HTTP client
urllib3 >= 1.26.19, < 3 - Sync HTTP client
opentelemetry-api >= 1.25.0 - Telemetry support
python-dateutil >= 2.9.0 - Date parsing

OpenFGA Server Version Features:

Batch Check: Requires v1.8.2+
Consistency Preferences: Requires v1.5.7+
Conflict Options: Requires v1.10.0+

The SDK is published to PyPI as openfga-sdk and can be installed via pip install openfga-sdk.

Sources: pyproject.toml35-42 uv.lock1-10 README.md75-120

Authentication and Authorization

The SDK supports three authentication methods configured via the Credentials class:

Configuration Example (OAuth2):

The OAuth2Client automatically handles token acquisition, caching, and refresh. Tokens are cached until expiry and automatically renewed when needed.

Sources: README.md151-204 openfga_sdk/credentials.py1-100 (inferred), Diagram 3 from architecture diagrams

Error Handling and Resilience

The SDK provides robust error handling with automatic retries:

Retry Behavior:

Automatic retry on 429 (rate limit) and 5xx (server error) responses
Default: 3 retries with exponential backoff and jitter
Minimum wait: 100ms, maximum wait: 600s
Configurable via RetryParams(max_retry, min_wait_in_ms)

Exception Hierarchy:

All exceptions include detailed error information: HTTP status, error code, message, and request ID for debugging.

Sources: README.md1264-1311 openfga_sdk/exceptions.py1-100 (inferred), Diagram 6 from architecture diagrams

Next Steps

For installation and initial setup, see Getting Started
For configuration details, see Configuration and Authentication
For API operation reference, see API Operations
For advanced features like telemetry and streaming, see Advanced Features
For contributing to the SDK, see Development and Contributing

Sources: Table of contents structure