Perform a List Objects call

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.

Before you start

You have obtained FGA API credentials and set FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
You have installed the SDK.
You have configured the authorization model and updated the relationship tuples.
You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

You have obtained FGA API credentials and set FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
You have installed the SDK.
You have configured the authorization model and updated the relationship tuples.
You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

You have obtained FGA API credentials and set FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
You have installed the SDK.
You have configured the authorization model and updated the relationship tuples.
You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

You have obtained FGA API credentials and set FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
You have installed the SDK.
You have configured the authorization model and updated the relationship tuples.
You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

You have obtained FGA API credentials and set FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
You have installed the SDK.
You have configured the authorization model and updated the relationship tuples.
You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

You have obtained FGA API credentials and set FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
You have installed the CLI.
You have configured the authorization model and updated the relationship tuples.
You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

You have obtained FGA API credentials and set FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
You have configured the authorization model and updated the relationship tuples.
You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

Step by step

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:

01. Configure the Auth0 FGA API client

Before calling the check API, you will need to configure the API client.

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 main

import (
    "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 os
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.client.models import ClientListObjectsRequest, ClientTuple
from openfga_sdk.models import RelationshipCondition
from 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.dev
export FGA_API_AUDIENCE=https://api.us1.fga.dev/
export FGA_API_TOKEN_ISSUER=auth.fga.dev
export FGA_STORE_ID=YOUR_STORE_ID
export FGA_MODEL_ID=YOUR_MODEL_ID
export FGA_CLIENT_ID=YOUR_CLIENT_ID
export FGA_CLIENT_SECRET=YOUR_CLIENT_SECRET
# Obtain these values from https://dashboard.fga.dev/ and keep credentials private.

To obtain the access token:

# 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.

02. Calling list objects API

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’.

Streamed List Objects

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.

Introduction to Auth0 FGA

Permissions Index

FGA Dashboard

Define your authorization model

Write Your Authorization Data

Add Authorization To Your API

Auth0 Relationship Sync

Advanced Modeling

Deprecation Notices & Migrations

Perform a List Objects call

Before you start

Step by step

01. Configure the Auth0 FGA API client

02. Calling list objects API

Streamed List Objects

Using Streamed List Objects

​Before you start

​Step by step

​01. Configure the Auth0 FGA API client

​02. Calling list objects API

​Streamed List Objects

​Using Streamed List Objects

​Related Sections

Before you start

Step by step

01. Configure the Auth0 FGA API client

02. Calling list objects API

Streamed List Objects

Using Streamed List Objects

Related Sections