Perform a List Objects call

note

Auth0 Fine Grained Authorization (FGA) is the early-stage product we are building at Auth0 to solve fine-grained authorization at scale. Sign up for the Developer Community Preview to try it out, and join our Discord community if you are interested in learning more about our plans.

Please note that at this point in time, it is not considered production-ready and does not come with any SLAs; availability and uptime are not guaranteed. Limitations of Auth0 FGA during the Developer Community Preview can be found here.

This section will illustrate how to perform a list objects request to determine all the objects of a given type a user has a specified relationship with.

Before You Start

Node.js

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

Go

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

.NET

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

Python

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

CLI

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the CLI.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_SERVER_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

curl

1. You have obtained the environment, store id, client id and client secret.
2. You have configured the authorization model and updated the relationship tuples.
3. You have loaded FGA_STORE_ID and FGA_SERVER_URL as environment variables.

Step By Step

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.

Node.js

const { CredentialsMethod, OpenFgaClient } = require('@openfga/sdk'); // OR import { CredentialsMethod, OpenFgaClient } from '@openfga/sdk';

// Ensure the environment variables are set
// FGA_API_SCHEME = 'https'
// FGA_API_HOST = 'api.us1.fga.dev' for Dev Preview and Early Access / 'api.playground.fga.dev' for the FGA Playground
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'fga.us.auth0.com' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

const fgaClient = new OpenFgaClient({
    apiScheme: process.env.FGA_API_SCHEME,
    apiHost: process.env.FGA_API_HOST,
    storeId: process.env.FGA_STORE_ID,
    authorizationModelId: process.env.FGA_MODEL_ID,
    credentials: { // Credentials are not needed if connecting to the Playground API
      method: CredentialsMethod.ClientCredentials,
      config: {
        apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER,
        apiAudience: process.env.FGA_API_AUDIENCE,
        clientId: process.env.FGA_CLIENT_ID,
        clientSecret: process.env.FGA_CLIENT_SECRET,
      },
    },
});

Go

import (
    "os"

    openfga "github.com/openfga/go-sdk"
    . "github.com/openfga/go-sdk/client"
    "github.com/openfga/go-sdk/credentials"
)

// Ensure the environment variables are set
// FGA_API_SCHEME = 'https'
// FGA_API_HOST = 'api.us1.fga.dev' for Dev Preview and Early Access / 'api.playground.fga.dev' for the FGA Playground
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'fga.us.auth0.com' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiScheme:      os.Getenv("FGA_API_SCHEME")
        ApiHost:        os.Getenv("FGA_API_HOST"),
        StoreId:        os.Getenv("FGA_STORE_ID"),
        AuthorizationModelId: openfga.PtrString(os.Getenv("FGA_MODEL_ID")),
        Credentials: &credentials.Credentials{ // Credentials are not needed if connecting to the Playground API
            Method: credentials.CredentialsMethodClientCredentials,
            Config: &credentials.Config{
                ClientCredentialsClientId:       os.Getenv("FGA_CLIENT_ID"),
                ClientCredentialsClientSecret:   os.Getenv("FGA_CLIENT_SECRET"),
                ClientCredentialsApiAudience:    os.Getenv("FGA_API_AUDIENCE"),
                ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
            },
        },
    })

    if err != nil {
        // .. Handle error
    }
}

.NET

using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

// Ensure the environment variables are set
// FGA_API_SCHEME = 'https'
// FGA_API_HOST = 'api.us1.fga.dev' for Dev Preview and Early Access / 'api.playground.fga.dev' for the FGA Playground
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'fga.us.auth0.com' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

class MyProgram {
    static async Task Main() {
        var configuration = new ClientConfiguration() {
            ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"),
            ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"),
            StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
            AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
            Credentials = new Credentials() { // Credentials are not needed if connecting to the Playground API
                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"),
                }
            }
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

Python

import os
import openfga_sdk
from openfga_sdk.client import OpenFgaClient
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# FGA_API_SCHEME = 'https'
# FGA_API_HOST = 'api.us1.fga.dev' for Dev Preview and Early Access / 'api.playground.fga.dev' for the FGA Playground
# FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
# FGA_API_TOKEN_ISSUER = 'fga.us.auth0.com' for Dev Preview and Early Access / not needed for the FGA Playground
# FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
# FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
# FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

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 = openfga_sdk.Configuration(
    api_scheme = os.environ.get('FGA_API_SCHEME'),
    api_host = os.environ.get('FGA_API_HOST'),
    store_id = os.environ.get('FGA_STORE_ID'),
    model_id = os.environ.get('FGA_MODEL_ID'),
    credentials = credentials, # Credentials are not needed if connecting to the Playground API
)

async with OpenFgaClient(configuration) as fga_client:
    api_response = await fga_client.read_authorization_models() # call requests
    await fga_client.close() # close when done

CLI

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

# Only for Dev Preview/Early Access environment
export FGA_SERVER_URL='https://api.us1.fga.dev'
export FGA_API_TOKEN_ISSUER = 'fga.us.auth0.com'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/'
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

# Only for Playground environment
# export FGA_SERVER_URL='https://api.playground.fga.dev'

curl

To obtain the access token:

# Not needed when calling the Playground API
curl -X POST \
   https://fga.us.auth0.com/oauth/token \
   -H 'content-type: application/json' \
   -d '{"client_id":"'$FGA_CLIENT_ID'","client_secret":"'$FGA_CLIENT_SECRET'","audience":"https://api.us1.fga.dev/","grant_type":"client_credentials"}'

# The response will be returned in the form
# {
#  "access_token": "eyJ...Ggg",
#  "expires_in": 86400,
#  "scope": "read:tuples write:tuples check:tuples ... write:authorization-models",
#  "token_type": "Bearer"
# }
# Store this `access_token` value in environment variable `FGA_BEARER_TOKEN`

# For non-playground environment
FGA_SERVER_URL='https://api.us1.fga.dev'
# For playground environment
# FGA_SERVER_URL='https://api.playground.fga.dev'

02. Calling List Objects API

To return all documents that user user:anne has relationship reader with:

Node.js

const response = await fgaClient.listObjects({
  user: "user:anne",
  relation: "reader",
  type: "document",
}, {
  authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
});
// response.objects = ["document:otherdoc", "document:planning"]

Go

options := ClientListObjectsOptions{
    AuthorizationModelId: openfga.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
}
body := ClientListObjectsRequest{
	User:     "user:anne",
	Relation: "reader",
	Type:     "document",
}
data, err := fgaClient.ListObjects(context.Background()).
  Body(requestBody).
  Options(options).
  Execute()

// data = { "objects": ["document:otherdoc", "document:planning"] }

.NET

var options = new ClientListObjectsOptions {
    AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
};
var body = new ClientListObjectsRequest {
    User = "user:anne",
    Relation = "reader",
    Type = "document",
};

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

// response.Objects = ["document:otherdoc", "document:planning"]

Python

options = {
    "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
}
body = ClientListObjectsRequest(
    user="user:anne",
    relation="reader",
    type="document",
)

response = await fga_client.list_objects(body, options)

# response.objects = ["document:otherdoc", "document:planning"]

CLI

fga query list-objects --store-id=${FGA_STORE_ID} --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw user:anne reader document

# Response: {"objects": ["document:otherdoc", "document:planning"]}

curl

curl -X POST $FGA_SERVER_URL/stores/$FGA_STORE_ID/list-objects \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{ "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
        "type": "document",
        "relation": "reader",
        "user":"user:anne"
      }'

# Response: {"objects": ["document:otherdoc", "document:planning"]}

The result document:otherdoc and document:planning are the document objects that user:anne has reader relationship with.

Related Sections

Take a look at the following section for more on how to perform authorization checks in your system

Auth0 FGA List Objects API

Read the List Objects API documentation and see how it works.

• More