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
- Go
- .NET
- Python
- CLI
- curl
- 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.
- You have installed the SDK.
- You have configured the authorization model and updated the relationship tuples.
- You have loaded
FGA_STORE_ID
andFGA_API_HOST
as environment variables.
- 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.
- You have installed the SDK.
- You have configured the authorization model and updated the relationship tuples.
- You have loaded
FGA_STORE_ID
andFGA_API_HOST
as environment variables.
- 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.
- You have installed the SDK.
- You have configured the authorization model and updated the relationship tuples.
- You have loaded
FGA_STORE_ID
andFGA_API_HOST
as environment variables.
- 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.
- You have installed the SDK.
- You have configured the authorization model and updated the relationship tuples.
- You have loaded
FGA_STORE_ID
andFGA_API_HOST
as environment variables.
- 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.
- You have configured the authorization model.
- You have loaded
FGA_STORE_ID
andFGA_SERVER_URL
as environment variables.
- 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.
- You have configured the authorization model and updated the relationship tuples.
- You have loaded
FGA_STORE_ID
andFGA_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
- Go
- .NET
- Python
- CLI
- curl
// 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
});
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
}
}
// 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);
}
}
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()
Set FGA_SERVER_URL according to the service you are using (e.g. https://api.fga.example)
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
- Go
- .NET
- Python
- CLI
- curl
const response = await fgaClient.listObjects({
user: "user:anne",
relation: "reader",
type: "document",
}, {
authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
});
// response.objects = ["document:otherdoc", "document:planning"]
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"] }
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"]
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"]
fga query list-objects --store-id=${FGA_STORE_ID} --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw user:anne reader document
# Response: {"objects": ["document:otherdoc", "document:planning"]}
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.