OpenFGA Java SDK Overview

Relevant source files

• .openapi-generator/FILES
• CHANGELOG.md
• README.md
• build.gradle
• publish.gradle
• src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
• src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java
• src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java

Purpose and Scope

This document provides a high-level introduction to the OpenFGA Java SDK: what it is, what it does, and how it integrates with the OpenFGA authorization system. It covers the SDK's architecture, main components, key features, and installation basics.

For detailed information on specific topics, see:

• Installation instructions and dependency configuration: Installation and Setup
• Client initialization and basic usage: Quick Start Guide
• Detailed architecture and component interactions: SDK Architecture Overview
• Complete API reference: API Operations Reference
• Advanced features like retry logic and telemetry: Advanced Features

---

What is OpenFGA?

OpenFGA is an open-source fine-grained authorization (FGA) service inspired by Google's Zanzibar paper. It provides a scalable, low-latency authorization system that enables developers to:

• Define authorization models using relationship-based access control
• Store relationship tuples (user-relation-object mappings)
• Perform authorization checks and queries
• Manage complex permission hierarchies

OpenFGA runs as a separate server that applications interact with via HTTP APIs.

Sources: README.md59-64

---

SDK Purpose and Scope

The OpenFGA Java SDK is an auto-generated client library that provides Java applications with a convenient interface to the OpenFGA authorization service. The SDK wraps the OpenFGA API definition and offers:

1. Simplified Client Interface - High-level methods that abstract common patterns
2. Direct API Access - Low-level access for fine-grained control
3. Authentication Management - Built-in support for API tokens and OAuth2 client credentials
4. Automatic Retry Logic - Transparent handling of transient failures
5. Telemetry Integration - OpenTelemetry metrics for observability

Current Version: 0.9.5
Maven Coordinates: dev.openfga:openfga-sdk:0.9.5
Minimum Java Version: Java 11

Sources: README.md1-13 build.gradle21-22 build.gradle28-30 publish.gradle7-9

---

Key Features

Dual-Layer Client Architecture

The SDK provides two levels of abstraction:

Component	Purpose	When to Use
OpenFgaClient	High-level interface with convenience methods	Default choice for most use cases
OpenFgaApi	Low-level API mapping	When you need direct control over API calls
ApiExecutor	Custom endpoint execution	For calling arbitrary OpenFGA endpoints

Authentication Support

The SDK supports multiple authentication modes:

• No Credentials - For local development or unauthenticated servers
• API Token - Static bearer token authentication
• OAuth2 Client Credentials - Automatic token acquisition, caching, and refresh

Token caching is automatic when using OAuth2, reducing the overhead of token exchanges.

Automatic Retry Mechanism

The SDK implements RFC 9110-compliant retry logic:

• Rate Limiting (429) - Always retried with Retry-After header support
• Server Errors (5xx) - Automatically retried (except 501 Not Implemented)
• Exponential Backoff - Applied when Retry-After header is not present
• Maximum Retries - Configurable up to 15 attempts (default: 3)

Transaction Control

Write operations support two modes:

• Transactional Mode (default) - All tuples succeed or fail together
• Non-Transactional Mode - Tuples processed in chunks, partial success possible

Observability

Built-in OpenTelemetry integration provides metrics for:

• Request duration and status
• Retry counts
• Credential request timing
• Query-specific metrics

Sources: README.md130-132 README.md156-209 CHANGELOG.md56-68 src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java370-416

---

SDK Architecture Overview

The following diagram shows how the SDK fits into an application's architecture and its relationship with the OpenFGA server:

Application Integration Architecture

Key Integration Points:

1. Application Layer - Configures and instantiates the SDK client
2. SDK Layer - Provides multiple abstraction levels (Client, Api, Executor)
3. Authentication Layer - Handles token lifecycle transparently
4. HTTP Layer - Manages connections, retries, and error handling
5. External Services - Communicates with OAuth and OpenFGA servers

Sources: src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java23-36 README.md136-209

---

Main SDK Components

The following diagram maps SDK concepts to concrete code entities:

Core SDK Components and Code Entities

Component Descriptions:

Component	File Path	Purpose
OpenFgaClient	src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java23	High-level client with convenience methods and automatic batching
OpenFgaApi	src/main/java/dev/openfga/sdk/api/OpenFgaApi.java	Low-level API client with direct HTTP endpoint mapping
ApiExecutor	Exposed via OpenFgaClient.apiExecutor()	Execute custom HTTP requests to arbitrary OpenFGA endpoints
ClientConfiguration	src/main/java/dev/openfga/sdk/api/configuration/ClientConfiguration.java	Configuration builder with validation
ApiClient	src/main/java/dev/openfga/sdk/api/ApiClient.java	HTTP client wrapper managing connections
OAuth2Client	src/main/java/dev/openfga/sdk/api/auth/OAuth2Client.java	Handles OAuth2 token acquisition and caching
HttpRequestAttempt	src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java	Retry strategy with exponential backoff
FgaConstants	src/main/java/dev/openfga/sdk/constants/FgaConstants.java	SDK-wide constants (timeouts, limits, defaults)

Sources: src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java23-80 README.md49-64

---

Installation and Distribution

Maven Central Distribution

The SDK is distributed via Maven Central under the coordinates:

Group ID:    dev.openfga
Artifact ID: openfga-sdk
Version:     0.9.5

Supported Build Tools

The SDK can be added to projects using various build tools:

Gradle (Groovy):

Gradle (Kotlin):

Maven:

Dependencies

The SDK has minimal required dependencies:

Dependency	Purpose
Jackson 2.20.1	JSON serialization/deserialization
OpenTelemetry 1.57.0	Metrics and observability (API only)
JSR305 3.0.2	Annotations for null safety

Java Version Requirements

• Minimum: Java 11
• Tested On: Java 11, 17, 21 (LTS versions)

The SDK is compiled with Java 11 source and target compatibility, ensuring maximum compatibility with modern Java applications.

Sources: README.md75-122 build.gradle28-30 build.gradle57-75 publish.gradle7-9

---

SDK Layers: Choosing the Right Abstraction

Layer Comparison

When to Use Each Layer

Use OpenFgaClient when:

• Building standard authorization features
• You want convenience methods like writeTuples() and deleteTuples()
• You need automatic batching and transaction control
• You want simplified client-side batch checking
• You're streaming large result sets with streamedListObjects()

Use OpenFgaApi when:

• You need direct control over API request structure
• You're implementing custom patterns not covered by OpenFgaClient
• You want to work with raw API request/response objects
• You need to handle specific API behaviors manually

Use ApiExecutor when:

• Calling custom or experimental OpenFGA endpoints
• The SDK doesn't yet support a specific API feature
• You need complete control over request construction

Example Method Mapping

Operation	OpenFgaClient	OpenFgaApi
Write tuples	writeTuples(List<ClientTupleKey>)	write(String storeId, WriteRequest)
Delete tuples	deleteTuples(List<ClientTupleKeyWithoutCondition>)	write(String storeId, WriteRequest)
Check authorization	check(ClientCheckRequest)	check(String storeId, CheckRequest)
Batch check	batchCheck(ClientBatchCheckRequest)	batchCheck(String storeId, BatchCheckRequest)
List objects	listObjects(ClientListObjectsRequest)	listObjects(String storeId, ListObjectsRequest)

Sources: src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java42-67 README.md311-1059

---

Getting Started Basics

Minimal Working Example

The simplest way to use the SDK is to create an OpenFgaClient with a configuration:

The client instance should be created once and reused throughout the application to benefit from:

• Connection pooling
• Token caching (OAuth2)
• Reduced initialization overhead

Common Operations Overview

Store Management:

Authorization Queries:

Relationship Tuples:

For complete examples, see:

• Quick Start Guide
• Basic Usage Examples
• Integration tests: src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java

Sources: README.md136-153 README.md718-737 src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java59-94

---

Version History and Stability

The SDK follows semantic versioning. Current version 0.9.5 indicates pre-1.0 development status, but the SDK is production-ready and actively maintained.

Recent Major Changes:

Version	Change	Impact
0.9.5	Added streamedListObjects API and ApiExecutor	New features for large result sets
0.9.2	Write conflict options (onDuplicate, onMissing)	Requires OpenFGA v1.10.0+
0.9.0	RFC 9110 Retry-After support, max retry enforcement	Improved retry behavior
0.8.0	Server-side batchCheck support	batchCheck renamed to clientBatchCheck (breaking)
0.7.0	Consistency parameter support	Requires OpenFGA v1.5.7+ with experimental flag
0.6.0	OpenTelemetry metrics reporting	New observability features

Breaking Changes History:

• v0.8.0: batchCheck() renamed to clientBatchCheck()
• v0.5.0: Removed excludedUsers from ListUsersResponse
• v0.4.0: Fixed reversed disableTransactions behavior in write operations

For complete version history, see CHANGELOG.md or Version Compatibility and Feature Matrix.

Sources: CHANGELOG.md1-282 build.gradle22

---

Next Steps

To continue learning about the SDK:

1. Set up the SDK - Installation and Setup
2. Try a quick example - Quick Start Guide
3. Understand core concepts - Core Concepts
4. Explore API operations - API Operations Reference
5. Add advanced features - Advanced Features
6. Study working examples - Example Applications

For SDK development and contribution, see:

• Development Guide
• GitHub Repository
• Contributing Guide

Sources: README.md15-57