This page provides a high-level overview of the OpenFGA Java SDK, including its architecture, core components, and key capabilities. This SDK is an autogenerated wrapper around the OpenFGA API that provides both high-level and low-level interfaces for interacting with OpenFGA authorization servers.
For installation and initial setup instructions, see Installation and Setup. For detailed API operation references, see Client APIs. For production-ready features like error handling and telemetry, see Advanced Features.
Sources: README.md1-124 build.gradle21-22
OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It provides a high-performance and flexible authorization/permission engine designed for application builders to model permission layers and integrate fine-grained authorization into their applications. The SDK communicates with OpenFGA API servers to manage authorization models, relationship tuples, and perform authorization queries.
Sources: README.md59-64
| Property | Value |
|---|---|
| Current Version | 0.9.5 |
| Group ID | dev.openfga |
| Artifact ID | openfga-sdk |
| Minimum Java Version | Java 17 |
| Repository | Maven Central |
| License | Apache-2.0 |
Sources: build.gradle21-34 publish.gradle7-9 README.md77-121
The SDK is organized into three primary architectural layers, each serving distinct purposes and exposing different levels of abstraction.
Sources: src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java23-36 src/main/java/dev/openfga/sdk/api/OpenFgaApi.java68-99 src/main/java/dev/openfga/sdk/api/client/ApiClient.java README.md124-153
Client Layer (High-Level Interface):
OpenFgaClient provides typed, developer-friendly methods for all OpenFGA operations with automatic configuration management, retry handling, and error translationApiExecutor offers an escape hatch for making custom HTTP requests to arbitrary OpenFGA endpointsClientConfiguration extends base Configuration with OpenFGA-specific settings like storeId and authorizationModelIdAPI Layer (Low-Level Interface):
OpenFgaApi implements direct mappings to OpenFGA REST API endpoints with minimal abstractiondev.openfga.sdk.api.model package represent API request/response structuresBaseStreamingApi handles Server-Sent Events for streaming operationsInfrastructure Layer:
ApiClient wraps Java's HttpClient and manages request lifecycleHttpRequestAttempt implements RFC 9110-compliant retry logic with exponential backoffOAuth2Client handles OAuth2 client credentials flow with token caching and proactive refreshConfiguration provides base settings for timeouts, retries, and telemetrySources: src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java1-80 src/main/java/dev/openfga/sdk/api/OpenFgaApi.java63-99
Sources: src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java28-80 src/main/java/dev/openfga/sdk/api/OpenFgaApi.java68-155
| Component | File Location | Purpose |
|---|---|---|
| OpenFgaClient | src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java23-1426 | Primary user-facing interface providing typed methods for stores, models, tuples, and authorization queries |
| OpenFgaApi | src/main/java/dev/openfga/sdk/api/OpenFgaApi.java68 | Low-level API providing direct access to REST endpoints with minimal abstraction |
| ApiExecutor | src/main/java/dev/openfga/sdk/api/client/ApiExecutor.java | Enables custom HTTP requests to arbitrary OpenFGA endpoints with automatic auth and retry handling |
| ClientConfiguration | src/main/java/dev/openfga/sdk/api/configuration/ClientConfiguration.java | Extends Configuration with storeId and authorizationModelId for client-level defaults |
| Configuration | src/main/java/dev/openfga/sdk/api/configuration/Configuration.java | Base configuration with API URL, credentials, timeouts, retry settings, and telemetry options |
| OAuth2Client | src/main/java/dev/openfga/sdk/api/auth/OAuth2Client.java | Manages OAuth2 token lifecycle with caching and proactive refresh (5-10 min before expiry) |
| HttpRequestAttempt | src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java | Executes HTTP requests with automatic retries for 429 and 5xx errors (except 501) |
| FgaConstants | src/main/java/dev/openfga/sdk/constants/FgaConstants.java | SDK-wide constants including default timeouts, retry limits, batch sizes, and API URLs |
Sources: src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java23-80 src/main/java/dev/openfga/sdk/api/OpenFgaApi.java68-99 README.md42-67
The SDK supports three authentication approaches:
Authorization headerOAuth2 tokens are proactively refreshed 5-10 minutes before expiry (with jitter) to prevent authentication failures and distribute token requests over time.
Sources: README.md134-239 src/main/java/dev/openfga/sdk/api/auth/OAuth2Client.java
Retry-After headers when provided, falls back to exponential backoff with jitterFgaApiValidationError, FgaApiRateLimitError, FgaApiAuthenticationError, etc.) for different failure modesSources: README.md132 CHANGELOG.md56-74 src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java
The write() method supports two modes:
Sources: README.md576-643 src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java369-532
Built-in OpenTelemetry support for observability:
fga-client.request.duration, fga-client.query.duration, fga-client.credentials.requestSources: README.md1095-1113 CHANGELOG.md142
The streamedListObjects() method uses Server-Sent Events (SSE) to efficiently stream large result sets, reducing memory consumption for operations returning many objects.
Sources: README.md1002-1085 CHANGELOG.md10
OpenFGA v1.10.0+ supports conflict resolution options:
onDuplicate: Controls behavior when creating existing tuples (ERROR or IGNORE)onMissing: Controls behavior when deleting non-existent tuples (ERROR or IGNORE)Sources: README.md645-713 CHANGELOG.md36-38
The SDK provides comprehensive coverage of OpenFGA API operations organized into categories:
| Category | Operations | Description |
|---|---|---|
| Stores | createStore, getStore, listStores, deleteStore | Manage OpenFGA stores |
| Authorization Models | writeAuthorizationModel, readAuthorizationModel, readAuthorizationModels, readLatestAuthorizationModel | Define and retrieve permission models |
| Relationship Tuples | write, read, readChanges, writeTuples, deleteTuples | Manage relationship data |
| Authorization Queries | check, expand, listObjects, listRelations, listUsers, streamedListObjects | Query permissions and relationships |
| Batch Operations | batchCheck, clientBatchCheck | Perform multiple checks efficiently |
| Assertions | writeAssertions, readAssertions | Test authorization models |
For detailed operation documentation, see API Operations Reference.
Sources: README.md24-52 src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java83-1426
The SDK is built using Gradle with the following characteristics:
Sources: build.gradle1-177 publish.gradle1-61 .github/workflows/
The recommended pattern for SDK usage:
OpenFgaClient once per application lifecyclestoreId and authorizationModelId at client level or override per requestThis pattern optimizes connection pooling, reduces authentication overhead (especially for OAuth2 client credentials), and improves overall performance.
Sources: README.md126-130 src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java28-80
Sources: README.md15-57
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.