This document provides an overview of the OpenFGA Go SDK, its architecture, and its core components. The SDK is an auto-generated client library for interacting with the OpenFGA authorization service. This page covers the SDK's purpose, structure, and primary layers.
For detailed usage instructions, see Getting Started. For information about specific SDK operations, see SDK Usage Guide. For development and contribution guidelines, see Development.
The OpenFGA Go SDK serves as a type-safe, idiomatic Go client for the OpenFGA fine-grained authorization API. It combines auto-generated API bindings with manually-crafted convenience methods to provide both low-level API access and high-level abstractions for common authorization patterns.
Key Characteristics:
OpenFgaApi) and data models are generated from OpenFGA's OpenAPI specificationOpenFgaClient wrapper provides convenience methods like BatchCheck, ListRelations, and non-transactional writesSources: README.md1-13 README.md59-64 CHANGELOG.md1-20
OpenFGA is an open-source fine-grained authorization (FGA) system inspired by Google's Zanzibar paper. It enables developers to implement relationship-based access control (ReBAC) by modeling permissions as relationships between users and resources.
Core Concepts:
Sources: README.md59-64
The SDK follows a three-tier architecture that separates concerns between user-facing convenience, generated API bindings, and low-level HTTP infrastructure:
Sources: README.md12-13 configuration.go1-125 docs/OpenFgaApi.md1-25
| Layer | Primary Files | Responsibilities |
|---|---|---|
| User-Facing | client/client.go | High-level methods (BatchCheck, ListRelations), request builders, non-transactional write coordination |
| Auto-Generated | api_open_fga.go, model_*.go, docs/ | API endpoint bindings, request/response models, builder patterns |
| Core Infrastructure | api_client.go, configuration.go, errors.go | HTTP client management, authentication, retry logic, error handling, telemetry hooks |
Sources: README.md12-13 configuration.go21-37
The OpenFgaClient is the recommended entry point for SDK users. It wraps the generated OpenFgaApi and provides:
High-Level Operations:
BatchCheck(): Server-side batch authorization checks (requires OpenFGA v1.8.0+)ClientBatchCheck(): Client-side parallel authorization checks using goroutinesListRelations(): Determine which relations a user has to an objectWrite() with non-transactional mode: Split large write operations across multiple requestsStreamedListObjects(): Stream large result sets via NDJSONConfiguration Management:
SetStoreId(), GetStoreId(): Dynamic store targeting for multi-tenant applicationsSetAuthorizationModelId(), GetAuthorizationModelId(): Model version managementSources: README.md108-110 CHANGELOG.md9-15 CHANGELOG.md51-62
The OpenFgaApi struct (defined in api_open_fga.go) is auto-generated from the OpenFGA OpenAPI specification. It provides direct access to all API endpoints:
API Categories:
CreateStore(), GetStore(), ListStores(), DeleteStore()WriteAuthorizationModel(), ReadAuthorizationModel(), ReadAuthorizationModels()Write(), Read(), ReadChanges()Check(), BatchCheck(), Expand(), ListObjects(), StreamedListObjects(), ListUsers()ReadAssertions(), WriteAssertions()Sources: docs/OpenFgaApi.md5-24
The Configuration struct manages SDK-wide settings:
Key Configuration Fields:
| Field | Type | Purpose |
|---|---|---|
ApiUrl | string | Base URL for OpenFGA API (e.g., "https://api.fga.example") |
Credentials | *credentials.Credentials | Authentication configuration (API token or OAuth2 client credentials) |
RetryParams | *RetryParams | Retry behavior (max attempts: 15, exponential backoff, respects Retry-After headers) |
HTTPClient | *http.Client | Custom HTTP client for advanced scenarios (connection pooling, timeouts) |
Telemetry | *telemetry.Configuration | OpenTelemetry metrics configuration |
DefaultHeaders | map[string]string | Headers sent with every request |
UserAgent | string | SDK user agent string (defaults to constants.UserAgent) |
Sources: configuration.go21-37 configuration.go93-124
The ClientConfiguration (used with OpenFgaClient) extends Configuration with store-specific settings:
Additional Fields:
StoreId: Default store identifier (can be overridden per-request)AuthorizationModelId: Default authorization model version (optional, recommended for production)Design Rationale: As of v0.4.0, StoreId and AuthorizationModelId were removed from the API-level configuration to support multi-store and multi-model applications more naturally. These values are now passed per-request or set as defaults in ClientConfiguration.
Sources: CHANGELOG.md137-149 README.md121-125
The SDK uses a hybrid approach combining auto-generated and manually-maintained code:
Regeneration Process:
api_open_fga.go, model files, and documentation.openapi-generator/FILES manifest tracks which files are auto-generatedGenerated Files Indicator: Auto-generated files contain header comments marking them as such and should not be modified directly. Changes to generated code must be made via sdk-generator repository.
Sources: README.md12-13 CONTRIBUTING.md42
The SDK supports three authentication methods via the credentials.Credentials struct:
| Method | Configuration | Use Case |
|---|---|---|
| None | No credentials | Local development, unauthenticated instances |
| API Token | CredentialsMethodApiToken + ApiToken | Simple bearer token authentication |
| OAuth2 Client Credentials | CredentialsMethodClientCredentials + client ID/secret/audience/issuer | Production environments with OAuth2 provider |
Authentication Flow:
Sources: README.md112-223 configuration.go30
The SDK provides structured error types that implement the error interface:
Error Type Hierarchy:
| Error Type | HTTP Status | Retryable | Description |
|---|---|---|---|
FgaApiValidationError | 400, 422 | No | Request parameter validation failures |
FgaApiAuthenticationError | 401, 403 | No | Authentication/authorization failures |
FgaApiNotFoundError | 404 | No | Store or model not found |
FgaApiRateLimitError | 429 | Yes | Rate limit exceeded (SDK retries with Retry-After header) |
FgaApiInternalError | 500-599 | Yes | Server errors (SDK retries with exponential backoff) |
Error Context: All error types include:
ResponseError: Underlying API error detailsMethod: HTTP methodRequestUrl: Full request URLSources: docs/OpenFgaApi.md67-80 CHANGELOG.md45-49
The SDK implements automatic retry logic for transient failures:
Retry Configuration (RetryParams):
Retry-After response headerRetry Behavior:
Sources: CHANGELOG.md45-50 configuration.go35 README.md110
The SDK integrates with OpenTelemetry to emit metrics about HTTP request performance:
Metrics Emitted:
fga-client.http_request.durationConfiguration: Set Telemetry field in Configuration to customize metric collection behavior.
Sources: CHANGELOG.md14 configuration.go36
For complete setup instructions including authentication, see Getting Started.
Sources: README.md75-131 README.md731-754
The SDK design balances several competing concerns:
1. Generated vs. Manual Code Separation: Auto-generated bindings ensure API compatibility, while manual wrappers provide idiomatic Go patterns and convenience methods.
2. Flexibility: Support for custom HTTP clients, per-request overrides, and both transactional and non-transactional operations accommodates diverse use cases.
3. Production Readiness: Built-in retry logic, rate limit handling, telemetry, and comprehensive error types reduce operational burden.
4. Multi-Tenancy Support: Per-request store and model overrides enable applications serving multiple tenants with isolated authorization data.
5. Developer Experience: Builder patterns, convenience methods, and streaming support simplify common authorization patterns.
Sources: README.md108-110 CHANGELOG.md137-149
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.