dotnet-sdk

.NET SDK for OpenFGA

This is an autogenerated SDK for OpenFGA. It provides a wrapper around the OpenFGA API definition.

Table of Contents

• About OpenFGA
• Resources
• Installation
• Getting Started
  • Initializing the API Client
  • Custom Headers
  • Get your Store ID
  • Calling the API
    • Stores
      • List All Stores
      • Create a Store
      • Get a Store
      • Delete a Store
    • Authorization Models
      • Read Authorization Models
      • Write Authorization Model
      • Read a Single Authorization Model
      • Read the Latest Authorization Model
    • Relationship Tuples
      • Read Relationship Tuple Changes (Watch)
      • Read Relationship Tuples
      • Write (Create and Delete) Relationship Tuples
    • Relationship Queries
      • Check
      • Batch Check
      • Client Batch Check
      • Expand
      • List Objects
      • Streamed List Objects
      • List Relations
      • List Users
    • Assertions
      • Read Assertions
      • Write Assertions
  • Calling Other Endpoints
  • Retries
  • API Endpoints
  • Models
  • OpenTelemetry
• Contributing
  • Issues
  • Pull Requests
• License

About

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google’s Zanzibar paper. It was created by the FGA team at Auth0 based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.

OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.

Resources

• OpenFGA Documentation
• OpenFGA API Documentation
• X
• OpenFGA Community
• Zanzibar Academy
• Google’s Zanzibar Paper (2019)

Installation

The OpenFGA .NET SDK is available on NuGet.

You can install it using:

• The dotnet CLI

dotnet add package OpenFga.Sdk

• The Package Manager Console inside Visual Studio:

Install-Package OpenFga.Sdk

• Visual Studio, Visual Studio for Mac and IntelliJ Rider

Search for and install OpenFga.Sdk in each of their respective package manager UIs.

Supported Frameworks

Supported targets: net8.0 (LTS), net9.0, netstandard2.0, net48.

We follow the official .NET support policy where practical: https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core

Unsupported / EOL runtimes (e.g. netcoreapp3.1, net7.0) may still function via the netstandard2.0 asset but are “best effort”; we may remove incidental compatibility or stop testing them without a major version bump.

See the full matrix, rationale, and troubleshooting guidance in SUPPORTED_FRAMEWORKS.md.

Getting Started

Initializing the API Client

Learn how to initialize your SDK

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.

The OpenFga.SdkClient will by default retry API requests up to 3 times on 429 and 5xx errors.

No Credentials

using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Configuration;
using OpenFga.Sdk.Exceptions;
using OpenFga.Sdk.Model;
using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Example {
    public class Example {
        public static async Task Main() {
            try {
                var configuration = new ClientConfiguration() {
                    ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL") ?? "http://localhost:8080", // required, e.g. https://api.fga.example
                    StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // not needed when calling `CreateStore` or `ListStores`
                    AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
                };
                var fgaClient = new OpenFgaClient(configuration);
                var response = await fgaClient.ReadAuthorizationModels();
            } catch (ApiException e) {
                 Debug.Print("Error: "+ e);
            }
        }
    }
}

API Token

using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Configuration;
using OpenFga.Sdk.Exceptions;
using OpenFga.Sdk.Model;
using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Example {
    public class Example {
        public static async Task Main() {
            try {
                var configuration = new ClientConfiguration() {
                    ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL") ?? "http://localhost:8080", // required, e.g. https://api.fga.example
                    StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // not needed when calling `CreateStore` or `ListStores`
                    AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
                    Credentials = new Credentials() {
                        Method = CredentialsMethod.ApiToken,
                        Config = new CredentialsConfig() {
                            ApiToken = Environment.GetEnvironmentVariable("FGA_API_TOKEN"),  // will be passed as the "Authorization: Bearer ${ApiToken}" request header
                        }
                    }
                };
                var fgaClient = new OpenFgaClient(configuration);
                var response = await fgaClient.ReadAuthorizationModels();
            } catch (ApiException e) {
                 Debug.Print("Error: "+ e);
            }
        }
    }
}

Client Credentials

using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Configuration;
using OpenFga.Sdk.Exceptions;
using OpenFga.Sdk.Model;
using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Example {
    public class Example {
        public static async Task Main() {
            try {
                var configuration = new ClientConfiguration() {
                    ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL") ?? "http://localhost:8080", // required, e.g. https://api.fga.example
                    StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // not needed when calling `CreateStore` or `ListStores`
                    AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
                    Credentials = new Credentials() {
                        Method = CredentialsMethod.ClientCredentials,
                        Config = new CredentialsConfig() {
                            // API Token Issuer can contain:
                            // - a scheme, defaults to https
                            // - a path, defaults to /oauth/token
                            // - a port
                            ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
                            ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
                            ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
                            ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
                        }
                    }
                };
                var fgaClient = new OpenFgaClient(configuration);
                var response = await fgaClient.ReadAuthorizationModels();
            } catch (ApiException e) {
                 Debug.Print("Error: "+ e);
            }
        }
    }
}

For a complete, runnable example, see Example1.

Custom Headers

Default Headers

You can set default headers that will be sent with every request during client initialization:

var configuration = new ClientConfiguration() {
    ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL") ?? "http://localhost:8080",
    StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
    AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
    DefaultHeaders = new Dictionary<string, string> {
        { "X-Custom-Header", "default-value" },
        { "X-Request-Source", "my-app" }
    }
};
var fgaClient = new OpenFgaClient(configuration);

Per-Request Headers

You can also send custom headers on a per-request basis by using the options parameter. Per-request headers will override any default headers set in the client configuration.

// Add custom headers to a specific request
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "viewer",
    Object = "document:roadmap"
};

var options = new ClientCheckOptions {
    Headers = new Dictionary<string, string> {
        { "X-Request-ID", "123e4567-e89b-12d3-a456-426614174000" },
        { "X-Custom-Header", "custom-value" } // These override any default headers
    }
};

var response = await fgaClient.Check(body, options);

Get your Store ID

You need your store id to call the OpenFGA API (unless it is to call the CreateStore or ListStores methods).

If your server is configured with authentication enabled, you also need to have your credentials ready.

Calling the API

Stores

List Stores

Get a paginated list of stores.

API Documentation

var options = new ClientListStoresOptions {
    PageSize = 10,
    ContinuationToken = "...",
};
var response = await fgaClient.ListStores(options);

// stores = [{ "id": "01FQH7V8BEG3GPQW93KTRFR8JB", "name": "FGA Demo Store", "created_at": "2022-01-01T00:00:00.000Z", "updated_at": "2022-01-01T00:00:00.000Z" }]

Create Store

Initialize a store.

API Documentation

var store = await fgaClient.CreateStore(new ClientCreateStoreRequest(){Name = "FGA Demo"})

// store.Id = "01FQH7V8BEG3GPQW93KTRFR8JB"

// store store.Id in database

// update the storeId of the current instance
fgaClient.StoreId = storeId;

// continue calling the API normally

Get Store

Get information about the current store.

API Documentation

Requires a client initialized with a storeId

var store = await fgaClient.GetStore();

// store = { "id": "01FQH7V8BEG3GPQW93KTRFR8JB", "name": "FGA Demo Store", "created_at": "2022-01-01T00:00:00.000Z", "updated_at": "2022-01-01T00:00:00.000Z" }

Delete Store

Delete a store.

API Documentation

Requires a client initialized with a storeId

var store = await fgaClient.DeleteStore();

Authorization Models

Read Authorization Models

Read all authorization models in the store.

API Documentation

var options = new ClientReadAuthorizationModelsOptions {
    PageSize = 10,
    ContinuationToken = "...",
};
var response = await fgaClient.ReadAuthorizationModels(options);

// response.AuthorizationModels = [
// { Id: "01GXSA8YR785C4FYS3C0RTG7B1", SchemaVersion: "1.1", TypeDefinitions: [...] },
// { Id: "01GXSBM5PVYHCJNRNKXMB4QZTW", SchemaVersion: "1.1", TypeDefinitions: [...] }];

Write Authorization Model

Create a new authorization model.

API Documentation

Note: To learn how to build your authorization model, check the Docs at https://openfga.dev/docs.

Learn more about the OpenFGA configuration language.

You can use the OpenFGA Syntax Transformer to convert between the friendly DSL and the JSON authorization model.

var body = new ClientWriteAuthorizationModelRequest {
    SchemaVersion = "1.1",
    TypeDefinitions = new List<TypeDefinition> {
        new() {Type = "user", Relations = new Dictionary<string, Userset>()},
        new() {Type = "document",
            Relations = new Dictionary<string, Userset> {
                {"writer", new Userset {This = new object()}}, {
                    "viewer", new Userset {
                        Union = new Usersets {
                            Child = new List<Userset> {
                                new() {This = new object()},
                                new() {ComputedUserset = new ObjectRelation {Relation = "writer"}}
                            }
                        }
                    }
                }
            },
            Metadata = new Metadata {
                Relations = new Dictionary<string, RelationMetadata> {
                    {"writer", new RelationMetadata {
                        DirectlyRelatedUserTypes = new List<RelationReference> {
                            new() {Type = "user"}
                        }
                    }}, {"viewer", new RelationMetadata {
                        DirectlyRelatedUserTypes = new List<RelationReference> {
                            new() {Type = "user"}
                        }
                    }}
                }
            }
        }
    }
};

var response = await fgaClient.WriteAuthorizationModel(body);

// response.AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1"

You can also load the authorization model from a JSON file:

var jsonString = await File.ReadAllTextAsync("authorization-model.json");
var body = ClientWriteAuthorizationModelRequest.FromJson(jsonString);

var response = await fgaClient.WriteAuthorizationModel(body);

// response.AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1"

Read a Single Authorization Model

Read a particular authorization model.

API Documentation

var options = new ClientReadAuthorizationModelOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
};

var response = await fgaClient.ReadAuthorizationModel(options);

// response.AuthorizationModel.Id = "01GXSA8YR785C4FYS3C0RTG7B1"
// response.AuthorizationModel.SchemaVersion = "1.1"
// response.AuthorizationModel.TypeDefinitions = [{ "type": "document", "relations": { ... } }, { "type": "user", "relations": { ... }}]

Read the Latest Authorization Model

Reads the latest authorization model (note: this ignores the model id in configuration).

API Documentation

var response = await fgaClient.ReadLatestAuthorizationModel();

// response.AuthorizationModel.Id = "01GXSA8YR785C4FYS3C0RTG7B1"
// response.AuthorizationModel.SchemaVersion = "1.1"
// response.AuthorizationModel.TypeDefinitions = [{ "type": "document", "relations": { ... } }, { "type": "user", "relations": { ... }}]

Relationship Tuples

Read Relationship Tuple Changes (Watch)

Reads the list of historical relationship tuple writes and deletes.

API Documentation

var startTime = DateTime.Parse("2022-01-01T00:00:00Z");
var body = new ClientReadChangesRequest { Type = "document", StartTime = startTime };
var options = new ClientReadChangesOptions {
    PageSize = 10,
    ContinuationToken = "...",
};

var response = await fgaClient.ReadChanges(body, options);

// response.ContinuationToken = ...
// response.Changes = [
//   { TupleKey: { User, Relation, Object }, Operation: TupleOperation.WRITE, Timestamp: ... },
//   { TupleKey: { User, Relation, Object }, Operation: TupleOperation.DELETE, Timestamp: ... }
// ]

Read Relationship Tuples

Reads the relationship tuples stored in the database. It does not evaluate nor exclude invalid tuples according to the authorization model.

API Documentation

// Find if a relationship tuple stating that a certain user is a viewer of a certain document
var body = new ClientReadRequest() {
    User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation = "viewer",
    Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
};

// Find all relationship tuples where a certain user has a relationship as any relation to a certain document
var body = new ClientReadRequest() {
    User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
};

// Find all relationship tuples where a certain user is a viewer of any document
var body = new ClientReadRequest() {
    User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation = "viewer",
    Object = "document:",
};

// Find all relationship tuples where any user has a relationship as any relation with a particular document

var body = new ClientReadRequest() {
    Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
};

// Read all stored relationship tuples
var body = new ClientReadRequest();

var options = new ClientReadOptions {
    PageSize = 10,
    ContinuationToken = "...",
};

var response = await fgaClient.Read(body, options);

// In all the above situations, the response will be of the form:
// response = { Tuples: [{ Key: { User, Relation, Object }, Timestamp }, ...]}

Write (Create and Delete) Relationship Tuples

Create and/or delete relationship tuples to update the system state.

API Documentation

Transaction mode (default)

By default, write runs in a transaction mode where any invalid operation (deleting a non-existing tuple, creating an existing tuple, one of the tuples was invalid) or a server error will fail the entire operation.

var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey> {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "viewer",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        },
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "viewer",
            Object = "document:0192ab2d-d36e-7cb3-a4a8-5d1d67a300c5",
        }
    },
    Deletes = new List<ClientTupleKeyWithoutCondition> {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "writer",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        }
    },
};
var options = new ClientWriteOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
};
var response = await fgaClient.Write(body, options);

Convenience WriteTuples and DeleteTuples methods are also available.

Non-transaction mode

The SDK will split the writes into separate requests and send them sequentially to avoid violating rate limits.

var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey> {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "viewer",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        },
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "viewer",
            Object = "document:0192ab2d-d36e-7cb3-a4a8-5d1d67a300c5",
        }
    },
    Deletes = new List<ClientTupleKeyWithoutCondition> {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "writer",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        }
    },
};
var options = new ClientWriteOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
    Transaction = new TransactionOptions() {
        Disable = true,
        MaxParallelRequests = 5, // Maximum number of requests to issue in parallel
        MaxPerChunk = 1, // Maximum number of requests to be sent in a transaction in a particular chunk
    }
};
var response = await fgaClient.Write(body, options);

Conflict Options for Write Operations

The SDK allows you to control how write conflicts are handled using the Conflict option:

• OnDuplicateWrites: Controls behavior when writing a tuple that already exists

  • OnDuplicateWrites.Error - Return error on duplicates (default)
  • OnDuplicateWrites.Ignore - Silently skip duplicate writes

• OnMissingDeletes: Controls behavior when deleting a tuple that doesn’t exist

  • OnMissingDeletes.Error - Return error on missing deletes (default)
  • OnMissingDeletes.Ignore - Silently skip missing deletes

var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey> {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "viewer",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        }
    },
    Deletes = new List<ClientTupleKeyWithoutCondition> {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "writer",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        }
    },
};
var options = new ClientWriteOptions {
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
    Conflict = new ConflictOptions {
       
       
    }
};
var response = await fgaClient.Write(body, options);

Relationship Queries

Check

Check if a user has a particular relation with an object.

API Documentation

var options = new ClientCheckOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
};
var body = new ClientCheckRequest {
    User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation = "writer",
    Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
};
var response = await fgaClient.Check(body, options);
// response.Allowed = true

Batch Check

Similar to check, but instead of checking a single user-object relationship, accepts a list of relationships to check. Requires OpenFGA server version 1.8.0 or greater.

This method automatically handles:

• Generating correlation IDs for checks that don’t have one
• Validating that correlation IDs are unique
• Chunking requests based on MaxBatchSize (default: 50)
• Executing batches in parallel based on MaxParallelRequests (default: 10)

If 429s or 5xxs are encountered, the underlying requests will retry up to 3 times before giving up.

Note: The order of BatchCheck results is not guaranteed to match the order of the checks provided. Use correlationId to pair responses with requests.

var options = new ClientBatchCheckOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
    MaxParallelRequests = 5, // Max number of requests to issue in parallel, defaults to 10
    MaxBatchSize = 20, // Max number of checks per batch request, defaults to 50
};
var body = new ClientBatchCheckRequest {
    Checks = new List<ClientBatchCheckItem>() {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "viewer",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
            ContextualTuples = new ContextualTupleKeys {
                TupleKeys = new List<TupleKey>() {
                    new() {
                        User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
                        Relation = "editor",
                        Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
                    }
                }
            },
            // CorrelationId is optional - will be auto-generated if not provided
        },
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "admin",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
            ContextualTuples = new ContextualTupleKeys {
                TupleKeys = new List<TupleKey>() {
                    new() {
                        User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
                        Relation = "editor",
                        Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
                    }
                }
            },
            CorrelationId = "check-admin-01234", // Custom correlation ID
        },
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "creator",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        },
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "deleter",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        }
    }
};

var response = await fgaClient.BatchCheck(body, options);

/*
response.Result = [{
  CorrelationId: "01JA8PM3QM7VBPGB8KMPK8SBD5", // Auto-generated
  Allowed: false,
  Request: {
    User: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation: "viewer",
    Object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
    ContextualTuples: { ... }
  }
}, {
  CorrelationId: "check-admin-01234", // Custom ID
  Allowed: false,
  Request: {
    User: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation: "admin",
    Object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
    ContextualTuples: { ... }
  }
}, {
  CorrelationId: "01JA8PMM6A90NV5ET0F28CYSZQ",
  Allowed: false,
  Request: {
    User: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation: "creator",
    Object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
  },
  Error: { Message: "...", InputError: "..." } // Error details if check failed
}, {
  CorrelationId: "01JA8PN7K2XBVW9R3FQMH5JZTA",
  Allowed: true,
  Request: {
    User: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation: "deleter",
    Object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
  }
}]
*/

Client Batch Check

Run a set of checks by making individual /check API calls in parallel on the client side. This is useful for small batches (< 10 checks) when you want more control over each individual request.

For larger batches or to use the server-side batch endpoint, use BatchCheck instead.

var options = new ClientBatchCheckClientOptions {
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
    MaxParallelRequests = 5, // Max number of requests to issue in parallel, defaults to 10
};
var body = new List<ClientCheckRequest>() {
    new() {
        User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
        Relation = "viewer",
        Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
    },
    new() {
        User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
        Relation = "admin",
        Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
    }
};

var response = await fgaClient.ClientBatchCheck(body, options);

/*
response.Responses = [{
  Allowed: false,
  Request: {
    User: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation: "viewer",
    Object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
  },
  Error: null
}, {
  Allowed: true,
  Request: {
    User: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation: "admin",
    Object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
  },
  Error: null
}]
*/

Expand

Expands the relationships in userset tree format.

API Documentation

var options = new ClientCheckOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
};
var body = new ClientExpandRequest {
    Relation = "viewer",
    Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
};
var response = await fgaClient.Expand(body, options);

// response.Tree.Root = {"name":"document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a#viewer","leaf":{"users":{"users":["user:81684243-9356-4421-8fbf-a4f8d36aa31b","user:f52a4f7a-054d-47ff-bb6e-3ac81269988f"]}}}

List Objects

List the objects of a particular type a user has access to.

API Documentation

var options = new ClientListObjectsOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
};
var body = new ClientListObjectsRequest {
    User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation = "viewer",
    Type = "document",
    ContextualTuples = new List<ClientTupleKey> {
        new() {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "writer",
            Object = "document:0192ab2d-d36e-7cb3-a4a8-5d1d67a300c5",
        },
    },
};
var response = await fgaClient.ListObjects(body, options);

// response.Objects = ["document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"]

Streamed List Objects

List objects of a particular type that the user has access to, using the streaming API.

The Streamed ListObjects API is very similar to the ListObjects API, with two key differences:

1. Streaming Results: Instead of collecting all objects before returning a response, it streams them to the client as they are collected.
2. No Pagination Limit: Returns all results without the 1000-object limit of the standard ListObjects API.

This is particularly useful when querying computed relations that may return large result sets.

API Documentation

var options = new ClientListObjectsOptions {
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
    Consistency = ConsistencyPreference.HIGHERCONSISTENCY
};

var objects = new List<string>();
await foreach (var response in fgaClient.StreamedListObjects(
    new ClientListObjectsRequest {
        User = "user:anne",
        Relation = "can_read",
        Type = "document"
    },
    options)) {
    objects.Add(response.Object);
}

// objects = ["document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"]

List Relations

List the relations a user has on an object.

ClientListRelationsRequest body =
    new ClientListRelationsRequest() {
        User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
        Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        Relations = new List<string> {"can_view", "can_edit", "can_delete", "can_rename"},
        ContextualTuples = new List<ClientTupleKey>() {
            new ClientTupleKey {
                User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
                Relation = "editor",
                Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
            }
        }
    };
var response = await fgaClient.ListRelations(body);

// response.Relations = ["can_view", "can_edit"]

List Users

List the users who have a certain relation to a particular type.

API Documentation

var body = new ClientListUsersRequest()
{
    Object = new FgaObject()
    {
        Type = "document",
        Id = "roadmap"
    },
    Relation = "can_read",
    UserFilters = new List<UserTypeFilter>
    {
        new UserTypeFilter()
        {
            Type = "user"
        }
    },
    ContextualTuples = new List<ClientTupleKey>() {
        new ClientTupleKey {
            User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
            Relation = "editor",
            Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        }
    }
};
var response = await fgaClient.ListUsers(body);

Assertions

Read Assertions

Read assertions for a particular authorization model.

API Documentation

var options = new ClientReadAssertionsOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
};
var response = await fgaClient.ReadAssertions(options);

Write Assertions

Update the assertions for a particular authorization model.

API Documentation

var options = new ClientWriteAssertionsOptions {
    // You can rely on the model id set in the configuration or override it for this specific request
    AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1",
};
var body = new List<ClientAssertion>() {new ClientAssertion() {
    User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    Relation = "viewer",
    Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
    Expectation = true,
}};
await fgaClient.WriteAssertions(body, options);

Calling Other Endpoints

For advanced use cases where you need to call API endpoints not yet available in the SDK’s typed methods, or when you need access to full response details (status code, headers, raw response), you can use ApiExecutor.ExecuteAsync().

Basic Usage

using OpenFga.Sdk.ApiClient;

var client = new OpenFgaClient(configuration);
var executor = client.ApiExecutor;

// Build a request using RequestBuilder
var request = new RequestBuilder<object> {
    Method = HttpMethod.Get,
    BasePath = configuration.ApiUrl,
    PathTemplate = "/stores/{store_id}",
    PathParameters = new Dictionary<string, string> { { "store_id", storeId } },
    QueryParameters = new Dictionary<string, string>()
};

// Execute and get full response details
var response = await executor.ExecuteAsync<object, GetStoreResponse>(request, "GetStore");

// Always check if the request was successful
if (!response.IsSuccessful) {
    Console.WriteLine($"Request failed: {response.StatusCode}");
    Console.WriteLine($"Error: {response.RawResponse}");
    return;
}

// Access response details
Console.WriteLine($"Status: {response.StatusCode}");
Console.WriteLine($"Headers: {response.Headers.Count}");
Console.WriteLine($"Raw JSON: {response.RawResponse}");
Console.WriteLine($"Data: {response.Data.Name}");

Fluent API Style

You can also use a fluent API for cleaner request building:

var request = RequestBuilder<object>
    .Create(HttpMethod.Post, configuration.ApiUrl, "/stores/{store_id}/check")
    .WithPathParameter("store_id", storeId)
    .WithQueryParameter("consistency", "HIGHER_CONSISTENCY")
    .WithBody(checkRequest);

var response = await executor.ExecuteAsync<object, CheckResponse>(request, "Check");

Custom Headers

var options = new ClientRequestOptions {
    Headers = new Dictionary<string, string> {
        { "X-Custom-Header", "value" },
        { "X-Trace-Id", traceId }
    }
};

var response = await executor.ExecuteAsync<object, TResponse>(
    request,
    "CustomEndpoint",
    options
);

Error Handling

Always check response.IsSuccessful and handle different status codes appropriately:

var response = await executor.ExecuteAsync<object, GetStoreResponse>(request, "GetStore");

if (!response.IsSuccessful)
{
    switch ((int)response.StatusCode)
    {
        case 404:
            Console.WriteLine("Store not found");
            break;
        case 401:
            Console.WriteLine("Unauthorized - check your credentials");
            break;
        case 429:
            Console.WriteLine("Rate limited - retry after delay");
            break;
        case >= 500:
            Console.WriteLine($"Server error: {response.RawResponse}");
            break;
        default:
            Console.WriteLine($"Request failed: {response.StatusCode}");
            break;
    }
    return;
}

// Safe to use response.Data here
Console.WriteLine($"Store Name: {response.Data.Name}");

Streaming Requests

For endpoints that stream results (such as /stores/{store_id}/streamed-list-objects), use ExecuteStreamingAsync. It returns an IAsyncEnumerable<TResponse> with no 1000-object pagination limit.

var request = RequestBuilder<object>
    .Create(HttpMethod.Post, configuration.ApiUrl, "/stores/{store_id}/streamed-list-objects")
    .WithPathParameter("store_id", storeId)
    .WithBody(new {
        user = "user:anne",
        relation = "can_read",
        type = "document",
        authorization_model_id = authorizationModelId
    });

await foreach (var item in executor.ExecuteStreamingAsync<object, StreamedListObjectsResponse>(
    request, "StreamedListObjects")) {
    Console.WriteLine(item.Object);
}

For a complete example with all features, see the ApiExecutor Example.

Retries

If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 3 times with a minimum wait time of 100 milliseconds between each attempt.

Retry-After Header Support

The SDK respects the Retry-After header from HTTP 429 (rate limit) responses per RFC 7231. When present, the SDK will use the delay specified in the header (supporting both delay-seconds and HTTP-date formats) instead of exponential backoff. If the Retry-After header is missing or invalid, the SDK automatically falls back to exponential backoff with jitter.

When a rate limit error cannot be retried (e.g., retry limit exceeded), the FgaApiRateLimitExceededError exception will include:

• RetryAfter: Parsed delay in seconds (if valid)
• RetryAfterRaw: Raw header value for debugging
• RetryAttempt: Number of retry attempts made

Customizing Retry Behavior

To customize retry behavior, create a RetryParams instance and assign values to the MaxRetry and MinWaitInMs constructor parameters. MaxRetry determines the maximum number of retries (up to 15), while MinWaitInMs sets the minimum wait time between retries in milliseconds (used for exponential backoff when Retry-After is not present).

Apply your custom retry values by passing the object to the ClientConfiguration constructor’s RetryParams parameter.

using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Configuration;
using OpenFga.Sdk.Exceptions;
using OpenFga.Sdk.Model;
using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Example {
    public class Example {
        public static async Task Main() {
            try {
                var configuration = new ClientConfiguration() {
                    ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL") ?? "http://localhost:8080", // required, e.g. https://api.fga.example
                    StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // not needed when calling `CreateStore` or `ListStores`
                    AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
                    RetryParams = new RetryParams() {
                        MaxRetry = 3, // retry up to 3 times on API requests
                        MinWaitInMs = 250 // wait a minimum of 250 milliseconds between requests
                    }
                };
                var fgaClient = new OpenFgaClient(configuration);
                var response = await fgaClient.ReadAuthorizationModels();
            } catch (ApiException e) {
                 Debug.Print("Error: "+ e);
            }
        }
    }
}

API Endpoints

Method	HTTP request	Description
BatchCheck	POST /stores/{store_id}/batch-check	Send a list of `check` operations in a single request
Check	POST /stores/{store_id}/check	Check whether a user is authorized to access an object
CreateStore	POST /stores	Create a store
DeleteStore	DELETE /stores/{store_id}	Delete a store
Expand	POST /stores/{store_id}/expand	Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship
GetStore	GET /stores/{store_id}	Get a store
ListObjects	POST /stores/{store_id}/list-objects	List all objects of the given type that the user has a relation with
ListStores	GET /stores	List all stores
ListUsers	POST /stores/{store_id}/list-users	List the users matching the provided filter who have a certain relation to a particular type.
Read	POST /stores/{store_id}/read	Get tuples from the store that matches a query, without following userset rewrite rules
ReadAssertions	GET /stores/{store_id}/assertions/{authorization_model_id}	Read assertions for an authorization model ID
ReadAuthorizationModel	GET /stores/{store_id}/authorization-models/{id}	Return a particular version of an authorization model
ReadAuthorizationModels	GET /stores/{store_id}/authorization-models	Return all the authorization models for a particular store
ReadChanges	GET /stores/{store_id}/changes	Return a list of all the tuple changes
StreamedListObjects	POST /stores/{store_id}/streamed-list-objects	Stream all objects of the given type that the user has a relation with
Write	POST /stores/{store_id}/write	Add or delete tuples from the store
WriteAssertions	PUT /stores/{store_id}/assertions/{authorization_model_id}	Upsert assertions for an authorization model ID
WriteAuthorizationModel	POST /stores/{store_id}/authorization-models	Create a new authorization model

Models

• Model.AbortedMessageResponse
• Model.Any
• Model.Assertion
• Model.AssertionTupleKey
• Model.AuthErrorCode
• Model.AuthorizationModel
• Model.BatchCheckItem
• Model.BatchCheckRequest
• Model.BatchCheckResponse
• Model.BatchCheckSingleResult
• Model.CheckError
• Model.CheckRequest
• Model.CheckRequestTupleKey
• Model.CheckResponse
• Model.Computed
• Model.Condition
• Model.ConditionMetadata
• Model.ConditionParamTypeRef
• Model.ConsistencyPreference
• Model.ContextualTupleKeys
• Model.CreateStoreRequest
• Model.CreateStoreResponse
• Model.Difference
• Model.ErrorCode
• Model.ExpandRequest
• Model.ExpandRequestTupleKey
• Model.ExpandResponse
• Model.FgaObject
• Model.ForbiddenResponse
• Model.GetStoreResponse
• Model.InternalErrorCode
• Model.InternalErrorMessageResponse
• Model.Leaf
• Model.ListObjectsRequest
• Model.ListObjectsResponse
• Model.ListStoresResponse
• Model.ListUsersRequest
• Model.ListUsersResponse
• Model.Metadata
• Model.Node
• Model.Nodes
• Model.NotFoundErrorCode
• Model.NullValue
• Model.ObjectRelation
• Model.PathUnknownErrorMessageResponse
• Model.ReadAssertionsResponse
• Model.ReadAuthorizationModelResponse
• Model.ReadAuthorizationModelsResponse
• Model.ReadChangesResponse
• Model.ReadRequest
• Model.ReadRequestTupleKey
• Model.ReadResponse
• Model.RelationMetadata
• Model.RelationReference
• Model.RelationshipCondition
• Model.SourceInfo
• Model.Status
• Model.Store
• Model.StreamResultOfStreamedListObjectsResponse
• Model.StreamedListObjectsResponse
• Model.Tuple
• Model.TupleChange
• Model.TupleKey
• Model.TupleKeyWithoutCondition
• Model.TupleOperation
• Model.TupleToUserset
• Model.TypeDefinition
• Model.TypeName
• Model.TypedWildcard
• Model.UnauthenticatedResponse
• Model.UnprocessableContentErrorCode
• Model.UnprocessableContentMessageResponse
• Model.User
• Model.UserTypeFilter
• Model.Users
• Model.Userset
• Model.UsersetTree
• Model.UsersetTreeDifference
• Model.UsersetTreeTupleToUserset
• Model.UsersetUser
• Model.Usersets
• Model.ValidationErrorMessageResponse
• Model.WriteAssertionsRequest
• Model.WriteAuthorizationModelRequest
• Model.WriteAuthorizationModelResponse
• Model.WriteRequest
• Model.WriteRequestDeletes
• Model.WriteRequestWrites

OpenTelemetry

This SDK supports producing metrics that can be consumed as part of an OpenTelemetry setup. For more information, please see the documentation

Contributing

See CONTRIBUTING for details.

Author

OpenFGA

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.

The code in this repo was auto generated by OpenAPI Generator from a template based on the csharp-netcore template, licensed under the Apache License 2.0.