Perform a List Objects call

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. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

Go

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

.NET

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

Python

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

CLI

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have configured the authorization model.
3. You have loaded FGA_STORE_ID and FGA_SERVER_URL as environment variables.

curl

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have configured the authorization model and updated the relationship tuples.
3. You have loaded FGA_STORE_ID and FGA_API_HOST 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 OpenFGA API Client

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

Node.js

// import the SDK
const { OpenFgaClient } = require('@openfga/sdk');

// Initialize the SDK with no auth - see "How to setup SDK client" for more options
const fgaClient = new OpenFgaClient({
  apiScheme: process.env.FGA_API_SCHEME, // Either "http" or "https", defaults to "https"
  apiHost: process.env.FGA_API_HOST, // required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
});

Go

import (
    . "github.com/openfga/go-sdk/client"
    "os"
)

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiScheme:            os.Getenv("FGA_SCHEME"), // Either "http" or "https", defaults to "https"
        ApiHost:              os.Getenv("FGA_API_HOST"), // required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: openfga.PtrString(os.Getenv("FGA_MODEL_ID")),  // Optional, can be overridden per request
    })

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

.NET

// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"), // Either "http" or "https", defaults to "https"
          ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"), // required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

Python

import os
import json
import openfga_sdk
from openfga_sdk.client import OpenFgaClient

configuration = openfga_sdk.ClientConfiguration(
    api_scheme = os.environ.get('FGA_API_SCHEME'), # Either "http" or "https", defaults to "https"
    api_host = os.environ.get('FGA_API_HOST'), # required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
    store_id = os.environ.get('FGA_STORE_ID') # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
    authorization_model_id = os.environ.get('FGA_MODEL_ID'), # Optional, can be overridden per request
)

# Enter a context with an instance of the OpenFgaClient
async with OpenFgaClient(configuration) as fga_client:
    api_response = await fga_client.read_authorization_models()
    await fga_client.close()

CLI

Set FGA_SERVER_URL according to the service you are using (e.g. https://api.fga.example)

curl

To obtain the access token:

Set FGA_SERVER_URL according to the service you are using (e.g. https://api.fga.example)

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

OpenFGA List Objects API

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

• More