List all objects a user is authorized to perform a specified action for a given resource type
This section describes how to perform a list objects request. The List Objects API allows you to retrieve all objects of a specified type that a user has a given relationship with. This can be used in scenarios like displaying all documents a user can read or listing resources a user can manage.
Consider the following model which includes a user that can have a reader relationship with a document:Assume that you want to list all objects of type document that user anne has reader relationship with:
Before calling the check API, you will need to configure the API client.
Node.js
Go
.NET
Python
Java
CLI
curl
const { CredentialsMethod, OpenFgaClient, ConsistencyPreference } = require('@openfga/sdk');const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL, // https://api.us1.fga.dev, or your store's eu1/au1 region storeId: process.env.FGA_STORE_ID, authorizationModelId: process.env.FGA_MODEL_ID, credentials: { method: CredentialsMethod.ClientCredentials, config: { apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER, // auth.fga.dev apiAudience: process.env.FGA_API_AUDIENCE, // URL for your store's region clientId: process.env.FGA_CLIENT_ID, clientSecret: process.env.FGA_CLIENT_SECRET, }, },});
package mainimport ( "os" . "github.com/openfga/go-sdk/client" "github.com/openfga/go-sdk/credentials")// Configure FGA_API_URL and FGA_API_AUDIENCE for your store's us1/eu1/au1 region.// Set FGA_STORE_ID, FGA_MODEL_ID, FGA_API_TOKEN_ISSUER, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.func main() { fgaClient, err := NewSdkClient(&ClientConfiguration{ ApiUrl: os.Getenv("FGA_API_URL"), StoreId: os.Getenv("FGA_STORE_ID"), AuthorizationModelId: os.Getenv("FGA_MODEL_ID"), Credentials: &credentials.Credentials{ Method: credentials.CredentialsMethodClientCredentials, Config: &credentials.Config{ ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"), ClientCredentialsApiAudience: os.Getenv("FGA_API_AUDIENCE"), ClientCredentialsClientId: os.Getenv("FGA_CLIENT_ID"), ClientCredentialsClientSecret: os.Getenv("FGA_CLIENT_SECRET"), }, }, }) if err != nil { panic(err) } _ = fgaClient // Use the client for the next request.}
using System.Collections.Generic;using OpenFga.Sdk.Client;using OpenFga.Sdk.Client.Model;using OpenFga.Sdk.Configuration;using OpenFga.Sdk.Model;using Environment = System.Environment;// FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.var fgaClient = new OpenFgaClient(new ClientConfiguration() { ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), Credentials = new Credentials() { Method = CredentialsMethod.ClientCredentials, Config = new CredentialsConfig() { 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"), } }});
import osfrom openfga_sdk.client import OpenFgaClient, ClientConfigurationfrom openfga_sdk.client.models import ClientListObjectsRequest, ClientTuplefrom openfga_sdk.models import RelationshipConditionfrom openfga_sdk.credentials import Credentials, CredentialConfiguration# FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.credentials = Credentials( method='client_credentials', configuration=CredentialConfiguration( api_issuer=os.environ.get('FGA_API_TOKEN_ISSUER'), api_audience=os.environ.get('FGA_API_AUDIENCE'), client_id=os.environ.get('FGA_CLIENT_ID'), client_secret=os.environ.get('FGA_CLIENT_SECRET'), ),)configuration = ClientConfiguration( api_url=os.environ.get('FGA_API_URL'), store_id=os.environ.get('FGA_STORE_ID'), authorization_model_id=os.environ.get('FGA_MODEL_ID'), credentials=credentials,)# Use: async with OpenFgaClient(configuration) as fga_client: ...
import dev.openfga.sdk.api.client.OpenFgaClient;import dev.openfga.sdk.api.configuration.ClientConfiguration;import dev.openfga.sdk.api.configuration.ClientCredentials;import dev.openfga.sdk.api.configuration.Credentials;import dev.openfga.sdk.api.configuration.ClientCheckOptions;import dev.openfga.sdk.api.configuration.ClientBatchCheckOptions;import dev.openfga.sdk.api.configuration.ClientWriteOptions;import dev.openfga.sdk.api.configuration.ClientListObjectsOptions;import dev.openfga.sdk.api.configuration.ClientListUsersOptions;import dev.openfga.sdk.api.client.model.*;import dev.openfga.sdk.api.model.*;import java.util.List;import java.util.Map;// FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.public class SdkSetupExample { public static void main(String[] args) throws Exception { var config = new ClientConfiguration() .apiUrl(System.getenv("FGA_API_URL")) .storeId(System.getenv("FGA_STORE_ID")) .authorizationModelId(System.getenv("FGA_MODEL_ID")) .credentials(new Credentials(new ClientCredentials() .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER")) .apiAudience(System.getenv("FGA_API_AUDIENCE")) .clientId(System.getenv("FGA_CLIENT_ID")) .clientSecret(System.getenv("FGA_CLIENT_SECRET")))); var fgaClient = new OpenFgaClient(config); }}
# Auth0 FGA managed API: choose your store's region (us1, eu1, or au1).export FGA_API_URL=https://api.us1.fga.devexport FGA_API_AUDIENCE=https://api.us1.fga.dev/export FGA_API_TOKEN_ISSUER=auth.fga.devexport FGA_STORE_ID=YOUR_STORE_IDexport FGA_MODEL_ID=YOUR_MODEL_IDexport FGA_CLIENT_ID=YOUR_CLIENT_IDexport FGA_CLIENT_SECRET=YOUR_CLIENT_SECRET# Obtain these values from https://dashboard.fga.dev/ and keep credentials private.
# Requires jq to safely encode credentials as JSON.curl -sS -X POST 'https://auth.fga.dev/oauth/token' \ -H 'content-type: application/json' \ --data "$(jq -n \ --arg client_id "$FGA_CLIENT_ID" \ --arg client_secret "$FGA_CLIENT_SECRET" \ --arg audience "$FGA_API_AUDIENCE" \ '{client_id: $client_id, client_secret: $client_secret, audience: $audience, grant_type: "client_credentials"}')"# Use the access_token in the response as FGA_BEARER_TOKEN for direct API calls.
To return all documents that user user:anne has relationship reader with:The result document:otherdoc and document:planning are the document objects that user:anne has reader relationship with.
WarningThe performance characteristics of the ListObjects endpoint vary drastically depending on the model complexity, number of tuples, and the relations it needs to evaluate. Relations with ‘and’ or ‘but not’ are more expensive to evaluate than relations with ‘or’.
The Streamed ListObjects API returns objects to the client as they are found instead of collecting them all before returning a response. See the Streamed List Objects API reference for request and response details.
The streaming functionality is currently available in the Node.js SDK, Go SDK, .NET SDK, Python SDK, and Java SDK.
