The OpenFGA Python SDK (openfga-sdk, current version 0.9.9) 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 VERSION.txt1
This SDK serves as the official Python client for OpenFGA, handling:
async/await) and synchronous execution patternsThe 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
The SDK implements a five-layer architecture from application code down to HTTP transport, allowing developers to choose their preferred abstraction level while sharing common infrastructure.
SDK Layer Architecture
Layer Descriptions:
| Layer | Primary Classes/Modules | Responsibility |
|---|---|---|
| High-Level Client Layer | openfga_sdk.client.client.OpenFgaClientopenfga_sdk.client.configuration.ClientConfiguration | Convenience methods (batch_check, write_tuples, delete_tuples), batch operations, transaction modes, simplified error handling |
| API Layer | openfga_sdk.api.open_fga_api.OpenFgaApiopenfga_sdk.models.* | Direct endpoint methods (check, write, read, expand, etc.), typed request/response models; auto-generated from OpenAPI specification |
| Client Infrastructure Layer | openfga_sdk.api_client.ApiClientopenfga_sdk.configuration.Configurationopenfga_sdk.oauth2.OAuth2Clientopenfga_sdk.telemetry.* | Request orchestration, authentication (OAuth2 with token caching), retry logic, telemetry collection, serialization/deserialization |
| Transport Layer | openfga_sdk.rest.RESTClientObjectRetry handler | HTTP I/O (aiohttp for async, urllib3 for sync), exponential backoff, rate limit handling (respects Retry-After headers) |
| Cross-Cutting | openfga_sdk.credentials.Credentialsopenfga_sdk.exceptions.* | Credential management (API token, client credentials), exception types (ApiException, FgaValidationException) |
The High-Level Client Layer provides the most convenient interface for common operations. The API Layer exposes all OpenFGA endpoints with full control and is the layer auto-generated from the OpenAPI spec. The Client Infrastructure Layer orchestrates requests, manages authentication with intelligent caching, and collects telemetry. The Transport Layer performs actual HTTP communication with built-in retry mechanisms for transient failures (429, 5xx errors).
Sources: openfga_sdk/__init__.py1-241 openfga_sdk/api/open_fga_api.py1-50 openfga_sdk/api_client.py (referenced in init), README.md122-287
The SDK maintains complete parallel implementations for asynchronous and synchronous usage patterns. Both implementations share identical APIs and logic but differ only in their concurrency primitives and HTTP libraries.
Async vs Sync Implementation Mapping
Implementation Comparison:
| Aspect | Async (openfga_sdk) | Sync (openfga_sdk.sync) |
|---|---|---|
| Import path | from openfga_sdk import OpenFgaClient | from openfga_sdk.sync import OpenFgaClient |
| HTTP library | aiohttp (version ≥3.9.3) | urllib3 (version ≥1.26.19, <3) |
| Execution model | async/await, asyncio.sleep | Blocking calls, time.sleep |
| Context manager | async with OpenFgaClient(...) | with OpenFgaClient(...) |
| Method invocation | await client.check(...) | client.check(...) |
| Usage context | asyncio event loop required | Standard Python scripts, sync frameworks |
All configuration classes, data models, validation logic, and telemetry definitions are shared between both implementations, ensuring consistent behavior and reducing code duplication. This architecture allows developers to use the same SDK in both async and sync codebases without mixing concurrency paradigms.
Sources: openfga_sdk/__init__.py1-6 openfga_sdk/api/open_fga_api.py1-50 openfga_sdk/sync/open_fga_api.py1-48 README.md266-287 pyproject.toml37-42
The SDK employs a hybrid development approach where core API bindings are auto-generated from an OpenAPI specification, while convenience wrappers and client infrastructure are manually maintained. The .openapi-generator-ignore file protects manual code from being overwritten during regeneration.
Code Generation Architecture
Code Generation Matrix:
| Module / Class | Status | Lines | Purpose |
|---|---|---|---|
openfga_sdk.api.open_fga_api.OpenFgaApi | Generated | ~5000+ | Type-safe methods for all API endpoints (check, write, read, expand, list_objects, etc.) |
openfga_sdk.models.* (90+ classes) | Generated | ~10000+ | Data model classes (CheckRequest, CheckResponse, TupleKey, AuthorizationModel, etc.) |
openfga_sdk.constants | Generated | ~10 | SDK version and constants |
docs/*.md | Generated | ~3000+ | API method documentation |
openfga_sdk.client.client.OpenFgaClient | Manual | ~800+ | Convenience methods (batch_check, write_tuples, delete_tuples, client_batch_check) |
openfga_sdk.client.configuration.ClientConfiguration | Manual | ~100+ | High-level client configuration (store_id, authorization_model_id, headers) |
openfga_sdk.oauth2.OAuth2Client | Manual | ~150+ | OAuth2 client credentials flow with token acquisition and caching |
openfga_sdk.credentials.* | Manual | ~150+ | Credential type selection (none, api_token, client_credentials) and validation |
openfga_sdk.telemetry.* | Manual | ~500+ | OpenTelemetry integration (counters, histograms, attribute extraction) |
openfga_sdk.configuration.Configuration | Manual | ~200+ | Low-level configuration (api_url, retry_params, timeout, telemetry) |
openfga_sdk.api_client.ApiClient | Generated + Manual | ~1500+ | Request orchestration with manual retry logic and telemetry extensions |
Sources: .openapi-generator/FILES1-191 openfga_sdk/__init__.py1-241 README.md12
The SDK relies on the following core dependencies:
| Dependency | Version Constraint | Purpose |
|---|---|---|
aiohttp | >=3.9.3 | Async HTTP client used by openfga_sdk.rest.RESTClientObject |
urllib3 | >=1.26.19,<3 | Sync HTTP client used by openfga_sdk.sync.rest.RESTClientObject |
python-dateutil | >=2.9.0 | Date/time parsing for API response models |
opentelemetry-api | >=1.25.0 | Metrics and observability via openfga_sdk.telemetry |
The SDK communicates with OpenFGA exclusively over HTTP REST. There is no gRPC dependency.
Sources: pyproject.toml37-42
Applications interact with the SDK through two primary entry points depending on their concurrency model:
For Async Applications:
For Sync Applications:
Both entry points expose the same method signatures and return the same model types from openfga_sdk.models.*. The only difference is the use of async with / await vs. plain with / direct calls. The SDK strongly recommends initializing OpenFgaClient once at application startup and reusing it to benefit from connection pooling, credential caching, and efficient resource management.
Sources: README.md134-287 README.md266-287
A typical SDK request follows a multi-phase execution pipeline with authentication, retry logic, and telemetry collection:
Request Execution Sequence
The configuration (including credentials) is typically created once at application startup and reused across all requests to benefit from:
Per the README: "We strongly recommend you initialize the OpenFgaClient only once and then re-use it throughout your app, otherwise you will incur the cost of having to re-initialize multiple times or at every request, the cost of reduced connection pooling and re-use, and would be particularly costly in the client credentials flow, as that flow will be preformed on every request."
Sources: README.md126-148 openfga_sdk/api/open_fga_api.py259-390 openfga_sdk/api_client.py (call_api method)
Sources: README.md14-73
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.
