Relationship Queries: Check, Read, Expand, ListObjects and ListUsers

In this guide you will learn the uses of and limitations for the Check, Read, Expand, and ListObjects API endpoints.

Before you start

In order to understand this guide correctly you must be familiar with some OpenFGA Concepts and know how to develop the things that we will list below. Assume that you have the following authorization model.
You have a type called document that can have a reader and writer. All writers are readers. bob has a writer relationship with document:planning.

Example authorization model

Bob has writer relationship with planning document

[
  {
    "user": "user:bob",
    "relation": "writer",
    "object": "document:planning"
  }
]

In addition, you will need to know the following:

Direct access

You need to know how to create an authorization model and create a relationship tuple to grant a user access to an object. Learn more →

OpenFGA concepts

A Type: a class of objects that have similar characteristics
A User: an entity in the system that can be related to an object
A Relation: is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system
An Object: represents an entity in the system. Users’ relationships to it can be define through relationship tuples and the authorization model
A Relationship Tuple: a grouping consisting of a user, a relation and an object stored in OpenFGA

Check

What is it for?

The Check API is an API endpoint that returns whether the user has a certain relationship with an object. OpenFGA will resolve all prerequisite relationships to establish whether a relationship exists.

When to use?

Check can be called if you need to establish whether a particular user has a specific relationship with a particular object. For example, you can call check to determine whether bob has a reader relationship with document:planning. The OpenFGA API will return true because there is an implied relationship as

every writer is also a reader
bob is a writer for document:planning

Caveats and when not to use it

Check is designed to answer the question “Does user:X have relationship Y with object:Z?”. It is not designed to answer the following questions:

“Who has relationship Y with object:Z?”
“What are the objects that userX has relationship Y with?”
“Why does user:X have relationship Y with object:Z?”

Batch Check

What is it for?

The Batch Check API is an API endpoint that allows you to check multiple user-object-relationship combinations in a single request.

When to use?

Batching authorization checks together in a single request significantly reduces overall network latency. Two scenarios are common to use Batch Check:

When determining if the user has access to a list of objects (such as Option 1 in Search with Permissions), filter and sort on your database, then call /batch-check. Repeat to perform pagination.
When determining fields on a web page the user has access to, call /batch-check for every relation necessary to show/hide each field.

For example, you can call Batch Check to determine whether bob has can_view_name, can_view_dob, and can_view_ssn relationships with patient_record:1. The OpenFGA API will return true depending on the level of access assigned to that user and the implied relationships inherited in the authorization model.

Caveats and when not to use it

If you are making less than 10 checks, it may be faster to call the Check API in parallel instead of Batch Check.

Read

What Is It For?

The Read API is an API endpoint that returns the relationship tuples that are stored in the system that satisfy a query.

When to use?

Read can be called if you need to get all the stored relationship tuples that relate:

user + relation + object
user + relation + object type
user + object with any relation
user + object type with any relation
relation + object for any user
object with any user and relation
all with any user, relation, or object

Initialize the SDK for Read and Expand

Set FGA_API_URL for your service (for example, https://api.fga.example) and FGA_STORE_ID for your store. Initialize once, then place the request snippets below in the same scope as the client. For Python, run requests inside the async with block; for Go, .NET, and Java, use the method that initializes the client. See SDK client setup for authentication options.

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

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL,
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional; overridable per request
});

import (
    "context"
    "os"

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

func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl: os.Getenv("FGA_API_URL"),
        StoreId: os.Getenv("FGA_STORE_ID"),
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
    })
    if err != nil {
        panic(err)
    }
    // Place a request below here.
}

using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;

var configuration = new ClientConfiguration {
    ApiUrl = System.Environment.GetEnvironmentVariable("FGA_API_URL") ?? "http://localhost:8080",
    StoreId = System.Environment.GetEnvironmentVariable("FGA_STORE_ID"),
    AuthorizationModelId = System.Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
};
var fgaClient = new OpenFgaClient(configuration);

import asyncio
import os
from openfga_sdk.client import ClientConfiguration, OpenFgaClient
from openfga_sdk.client.models import ClientExpandRequest
from openfga_sdk.models import ReadRequestTupleKey

async def main():
    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"),
    )
    async with OpenFgaClient(configuration) as fga_client:
        # Place a request below here.
        pass

asyncio.run(main())

import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import dev.openfga.sdk.api.client.model.*;

public class Example {
    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_AUTHORIZATION_MODEL_ID"));
        var fgaClient = new OpenFgaClient(config);
        // Place a request below here.
    }
}

export FGA_API_URL="https://api.fga.example"
export FGA_STORE_ID="<store-id>"

export FGA_API_URL="https://api.fga.example"
export FGA_STORE_ID="<store-id>"
# Remove the Authorization header below if your service does not require it.

For example, to query if bob has a writer relationship on document:planning (essentially finding out if a tuple exists), one can ask

const { tuples } = await fgaClient.read({
  user: "user:bob",
  relation: "writer",
  object: "document:planning",
});

options := ClientReadOptions{}
body := ClientReadRequest{
    User: PtrString("user:bob"),
    Relation: PtrString("writer"),
    Object: PtrString("document:planning"),
}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {
    User = "user:bob",
    Relation = "writer",
    Object = "document:planning",
};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey(
    user="user:bob",
    relation="writer",
    object="document:planning",
)
response = await fga_client.read(body, options)

var body = new ClientReadRequest()
    .user("user:bob")
    .relation("writer")
    ._object("document:planning");
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID} --user user:bob --relation writer --object document:planning

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"user":"user:bob","relation":"writer","object":"document:planning"}}'

read("user:bob", "writer", "document:planning");

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

For example, to query all the stored relationship tuples bob has a writer relationship with on type document:, one can ask

const { tuples } = await fgaClient.read({
  user: "user:bob",
  relation: "writer",
  object: "document:",
});

options := ClientReadOptions{}
body := ClientReadRequest{
    User: PtrString("user:bob"),
    Relation: PtrString("writer"),
    Object: PtrString("document:"),
}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {
    User = "user:bob",
    Relation = "writer",
    Object = "document:",
};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey(
    user="user:bob",
    relation="writer",
    object="document:",
)
response = await fga_client.read(body, options)

var body = new ClientReadRequest()
    .user("user:bob")
    .relation("writer")
    ._object("document:");
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID} --user user:bob --relation writer --object document:

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"user":"user:bob","relation":"writer","object":"document:"}}'

read("user:bob", "writer", "document:");

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

For example, to query all the stored relationship tuples bob has on type document:planning, one can ask

const { tuples } = await fgaClient.read({
  user: "user:bob",
  object: "document:planning",
});

options := ClientReadOptions{}
body := ClientReadRequest{
    User: PtrString("user:bob"),
    Object: PtrString("document:planning"),
}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {
    User = "user:bob",
    Object = "document:planning",
};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey(
    user="user:bob",
    object="document:planning",
)
response = await fga_client.read(body, options)

var body = new ClientReadRequest()
    .user("user:bob")
    ._object("document:planning");
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID} --user user:bob --object document:planning

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"user":"user:bob","object":"document:planning"}}'

read("user:bob", "document:planning");

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

For example, to query all the stored relationship tuples bob has on object type document:, one can ask

const { tuples } = await fgaClient.read({
  user: "user:bob",
  object: "document:",
});

options := ClientReadOptions{}
body := ClientReadRequest{
    User: PtrString("user:bob"),
    Object: PtrString("document:"),
}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {
    User = "user:bob",
    Object = "document:",
};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey(
    user="user:bob",
    object="document:",
)
response = await fga_client.read(body, options)

var body = new ClientReadRequest()
    .user("user:bob")
    ._object("document:");
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID} --user user:bob --object document:

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"user":"user:bob","object":"document:"}}'

read("user:bob", "document:");

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

For example, to query all the stored relationship tuples which have the writer relation on object document:planning, one can ask

const { tuples } = await fgaClient.read({
  relation: "writer",
  object: "document:planning",
});

options := ClientReadOptions{}
body := ClientReadRequest{
    Relation: PtrString("writer"),
    Object: PtrString("document:planning"),
}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {
    Relation = "writer",
    Object = "document:planning",
};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey(
    relation="writer",
    object="document:planning",
)
response = await fga_client.read(body, options)

var body = new ClientReadRequest()
    .relation("writer")
    ._object("document:planning");
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID} --relation writer --object document:planning

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"relation":"writer","object":"document:planning"}}'

read("writer", "document:planning");

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

For example, to query all the stored relationship tuples for object document:planning, one can ask

const { tuples } = await fgaClient.read({
  object: "document:planning",
});

options := ClientReadOptions{}
body := ClientReadRequest{
    Object: PtrString("document:planning"),
}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {
    Object = "document:planning",
};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey(
    object="document:planning",
)
response = await fga_client.read(body, options)

var body = new ClientReadRequest()
    ._object("document:planning");
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID} --object document:planning

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"object":"document:planning"}}'

read("document:planning");

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

7. Read all tuples for any user, relation, or object

For example, to query all stored relationship tuples, one can ask

const { tuples } = await fgaClient.read({});

options := ClientReadOptions{}
body := ClientReadRequest{}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey()
response = await fga_client.read(body, options)

var body = new ClientReadRequest();
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID}

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{}'

read();

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

Caveats and when not to use it

The Read API will only return all the stored relationships that match the query specification. It does not expand or traverse the graph by taking the authorization model into account. For example, if you specify that writers are viewers in the authorization model, the Read API will ignore that and it will return tuples where a user is a viewer if and only if the (user_id, "viewer", object_type:object_id) relationship tuple exists in the system. In the following case, although all writers have reader relationships for document objects and bob is a writer for document:planning, if you query for all objects that bob has reader relationships, it will not return document:planning.

const { tuples } = await fgaClient.read({
  user: "user:bob",
  relation: "reader",
  object: "document:",
});

options := ClientReadOptions{}
body := ClientReadRequest{
    User: PtrString("user:bob"),
    Relation: PtrString("reader"),
    Object: PtrString("document:"),
}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {
    User = "user:bob",
    Relation = "reader",
    Object = "document:",
};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey(
    user="user:bob",
    relation="reader",
    object="document:",
)
response = await fga_client.read(body, options)

var body = new ClientReadRequest()
    .user("user:bob")
    .relation("reader")
    ._object("document:");
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID} --user user:bob --relation reader --object document:

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"user":"user:bob","relation":"reader","object":"document:"}}'

read("user:bob", "reader", "document:");

Response

{
  "tuples": []
}

Although bob is a writer to document:planning and every writer is also a reader, the Read API will return an empty list because there are no stored relationship tuples that relate bob to document:planning as reader.

Expand

What is it for?

The Expand API returns all users (including users and usersets) that have a specific relationship with an object. The response is represented as a tree of users or usersets. To build the full graph of access, you would need to recursively call expand on the leaves returned from the previous expand call.

When to use?

Expand is used for debugging and to understand why a user has a particular relationship with a specific object. Reuse the SDK initialization from the Read examples. Replace the example authorization model ID below with the ID of the model you want to expand. For example, to understand why bob can have a reader relationship with document:planning, one could first call

const { tree } = await fgaClient.expand({
  relation: "reader",
  object: "document:planning",
}, {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
});

options := ClientExpandOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}
body := ClientExpandRequest{
    Relation: "reader",
    Object: "document:planning",
}
data, err := fgaClient.Expand(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientExpandOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientExpandRequest {
    Relation = "reader",
    Object = "document:planning",
};
var response = await fgaClient.Expand(body, options);

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA",
}
body = ClientExpandRequest(
    relation="reader",
    object="document:planning",
)
response = await fga_client.expand(body, options)

var options = new ClientExpandOptions()
    .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");
var body = new ClientExpandRequest()
    .relation("reader")
    ._object("document:planning");
var response = fgaClient.expand(body, options).get();

fga query expand --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA reader document:planning

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/expand" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"relation":"reader","object":"document:planning"},"authorization_model_id":"01HVMMBCMGZNT3SED4Z17ECXCA"}'

expand(
  "reader",
  "document:planning",
  authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA"
);

The result of this call will be like

Response

{
  "tree": {
    "root": {
      "type": "document:planning#reader",
      "leaf": {
        "computed": {
          "userset": "document:planning#writer"
        }
      }
    }
  }
}

The returned tree will contain writer, for which we will call

const { tree } = await fgaClient.expand({
  relation: "writer",
  object: "document:planning",
}, {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
});

options := ClientExpandOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}
body := ClientExpandRequest{
    Relation: "writer",
    Object: "document:planning",
}
data, err := fgaClient.Expand(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientExpandOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientExpandRequest {
    Relation = "writer",
    Object = "document:planning",
};
var response = await fgaClient.Expand(body, options);

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA",
}
body = ClientExpandRequest(
    relation="writer",
    object="document:planning",
)
response = await fga_client.expand(body, options)

var options = new ClientExpandOptions()
    .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");
var body = new ClientExpandRequest()
    .relation("writer")
    ._object("document:planning");
var response = fgaClient.expand(body, options).get();

fga query expand --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA writer document:planning

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/expand" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tuple_key":{"relation":"writer","object":"document:planning"},"authorization_model_id":"01HVMMBCMGZNT3SED4Z17ECXCA"}'

expand(
  "writer",
  "document:planning",
  authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA"
);

The result of this call will be like

Response

{
  "tree": {
    "root": {
      "type": "document:planning#writer",
      "leaf": {
        "users": {
          "users": [
            "user:bob"
          ]
        }
      }
    }
  }
}

From there, we will learn that

those related to document:planning as reader are all those who are related to that document as writer
bob is related to document:planning as writer

ListObjects

What is it for?

The ListObjects API is an API endpoint that returns the list of all the objects of a particular type that a specific user has a specific relationship with. It provides a solution to the Search with Permissions (Option 3) use case for access-aware filtering on small object collections.

When to use?

Use the ListObjects API to get what objects a user can see based on the relationships they have. See Search with Permissions for more guidance. There’s two variations of the List Objects API.

The standard version, which waits until all results are ready and sends them in one response.
The streaming version, which should be used if you want the individual results as soon as they become available.

Caveats

ListObjects will return the results found within the time allotted (listObjectsDeadline, default: 3s) up to the maximum number of results configured (listObjectsMaxResults, default: 1000). See Configuring the Server) for more on how to change the default configuration.

If you set listObjectsDeadline to 1s, the server will spend at most 1 second finding results.
If you set listObjectsMaxResults to 10, the server will return, at most, 10 objects.

If the number of objects of that type is high, you should set a high value for listObjectsDeadline. If the number of objects of that type the user could have access to is high, you should set a high value for listObjectsMaxResults.

ListUsers

What is it for?

The ListUsers API is an API endpoint that that returns all users of a given type that have a specified relationship with an object.

When to use?

Use the ListUsers API to get which users have a relation to a specific object.

Caveats

ListUsers will return the results found within the time allotted (listUsersDeadline, default: 3s) up to the maximum number of results configured (listUsersMaxResults, default: 1000). See Configuring the Server) for more on how to change the default configuration.

If you set listUsersDeadline to 1s, the server will spend at most 1 second finding results.
If you set listUsersMaxResults to 10, the server will return, at most, 10 objects.

If the number of users matching that filter is high, you should set a high value for listUsersDeadline. If the number of users matching that filter that could have that relation with the object is high, you should set a high value for listUsersMaxResults.

Summary

	Check	Read	Expand	ListObjects	ListUsers
Purpose	Check if user has particular relationship with certain object	Return all stored relationship tuples that match query	Expand the specific relationship on a particular object	List all objects of a particular type that a user has a specific relationship with	List all users of a particular type that have a relation to a specific object
When to use	Validate if user X can perform Y on object Z	List stored relationships in system	Understand why user X can perform Y on object Z	Filter the objects a user has access to	List the users that have access to an object

Check out this additional content for more information on how to query relationships.

Check API Reference

Official reference guide for the Check API

Read API Reference

Official reference guide for the Read API

Expand API Reference

Official reference guide for the Expand API

ListObjects API Reference

Official reference guide for the ListObjects API

ListUsers API Reference

Official reference guide for the ListUsers API

​Before you start

​Direct access

​OpenFGA concepts

​Check

​What is it for?

​When to use?

​Caveats and when not to use it

​Batch Check

​What is it for?

​When to use?

​Caveats and when not to use it

​Read

​What Is It For?

​When to use?

​1. Read a tuple related to a particular user, relation, and object

​2. Read all tuples related to a particular user, relation, and object type

​3. Read all tuples related to a particular user and object with any relation

​4. Read all tuples related to a particular user and object type with any relation

​5. Read all tuples related to a particular relation and object for any user

​6. Read all tuples related to a particular object with any user or relation

​7. Read all tuples for any user, relation, or object

​Caveats and when not to use it

​Expand

​What is it for?

​When to use?

​ListObjects

​What is it for?

​When to use?

​Caveats

​ListUsers

​What is it for?

​When to use?

​Caveats

​Summary

​Related Sections

Check API Reference

Read API Reference

Expand API Reference

ListObjects API Reference

ListUsers API Reference

Before you start

Direct access

OpenFGA concepts

Check

What is it for?

When to use?

Caveats and when not to use it

Batch Check

What is it for?

When to use?

Caveats and when not to use it

Read

What Is It For?

When to use?

1. Read a tuple related to a particular user, relation, and object

2. Read all tuples related to a particular user, relation, and object type

3. Read all tuples related to a particular user and object with any relation

4. Read all tuples related to a particular user and object type with any relation

5. Read all tuples related to a particular relation and object for any user

6. Read all tuples related to a particular object with any user or relation

7. Read all tuples for any user, relation, or object

Caveats and when not to use it

Expand

What is it for?

When to use?

ListObjects

What is it for?

When to use?

Caveats

ListUsers

What is it for?

When to use?

Caveats

Summary

Related Sections