Perform a List Users call

This section will illustrate how to perform a list users request. The List Users call allows you to retrieve a list of users that have a specific relationship with a given object. This can be used in scenarios such as retrieving users who have access to a resource or managing members in a group.

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_URL 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_URL 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_URL 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_URL 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_URL 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_URL 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_URL 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_URL as environment variables.

Java

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_URL 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_URL 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_URL and, if needed, FGA_API_TOKEN.
2. You have configured the authorization model.
3. You have loaded FGA_STORE_ID and FGA_API_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_URL 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_URL as environment variables.

Step by step

Consider the following model which includes a user that can have a reader relationship with a document:

model
  schema 1.1

type user

type document
  relations
    define reader: [user]

Assume that you want to list all users of type user that have a reader relationship with document:planning:

01. Configure the OpenFGA API client

Before calling the List Users 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({
  apiUrl: process.env.FGA_API_URL, // required, e.g. https://api.fga.example
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
});

Go

import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. 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: 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() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. 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 asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    configuration = ClientConfiguration(
        api_url = os.environ.get('FGA_API_URL'), # required, e.g. 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()

asyncio.run(main())

Java

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

public class Example {
  public static void main(String[] args) throws Exception {
      var config = new ClientConfiguration()
              .apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "https://localhost:8080"
              .storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores()
              .authorizationModelId(System.getenv("FGA_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

CLI

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

curl

To obtain the access token:

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

02. Calling List Users API

To return all users of type user that have have the reader relationship with document:planning:

Node.js

const response = await fgaClient.listUsers({
  object: {
    type: "document",
    id: "planning"
  },
  user_filters: [{
    type: "user"
  }],
  relation: "reader",
}, {
  authorization_model_id: "01HVMMBCMGZNT3SED4Z17ECXCA",
});
// response.users = [{"object":{"type":"user","id":"anne"}},{"object":{"type":"user","id":"beth"}}]

Go

options := ClientListUsersOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

userFilters := []openfga.UserTypeFilter{{ Type:"user" }}

body := ClientListUsersRequest{
    Object:       openfga.Object{
        Type:    "document",
        Id:      "planning",
    },
    Relation:     "reader",
    UserFilters:   userFilters,
}

data, err := fgaClient.ListUsers(context.Background()).
    Body(body).
    Options(options).
    Execute()

// data.Users = [{"object":{"type":"user","id":"anne"}}, {"object":{"type":"user","id":"beth"}}]

.NET

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientListUsersRequest {
    Object = new FgaObject {
      Type = "document",
      Id = "planning"
    },
    Relation = "reader",
    UserFilters = new List<UserTypeFilter> {
      new() {
        Type = "user"
      }
    }
    
};

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

// response.Users = [{"object":{"type":"user","id":"anne"}},{"object":{"type":"user","id":"beth"}}]

Python

  options = {
      "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
  }

  userFilters = [
      UserTypeFilter(type="user")
  ]

  body = ClientListUsersRequest(
      object=FgaObject(type="document",id="planning"),
      relation="reader",
      user_filters=userFilters,
  )

  response = await fga_client.list_users(body, options)

  # response.users = [{"object":{"type":"user","id":"anne"}},{"object":{"type":"user","id":"beth"}}]

Java

var options = new ClientListUsersOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var userFilters = new ArrayList<UserTypeFilter>() {
  {
      add(new UserTypeFilter().type("user"));
  }
};


var body = new ClientListUsersRequest()
        ._object(new FgaObject().type("document").id("planning"))
        .relation("reader")
        .userFilters(userFilters);

var response = fgaClient.listUsers(body, options).get();

// response.getUsers() = [{"object":{"type":"user","id":"anne"}},{"object":{"type":"user","id":"beth"}}]

CLI

fga query list-users --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA --object document:planning --relation reader --user-filter user 

# Response: {"users": [{"object":{"type":"user","id":"anne"}}, {"object":{"type":"user","id":"beth"}}]}

curl

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/list-users \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{
        "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA",
        "object": {
          "type: "document",
          "id": "planning",
        },
        "relation": "reader",
        "user_filters": [
          { 
            "type": "user"
          }
        ]
    }'


# Response: {"users": [{"object":{"type":"user","id":"anne"}}, {"object":{"type":"user","id":"beth"}}]}

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

Warning

The performance characteristics of the List Users 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 particularly expensive to evaluate.

Usersets

In the above example, only specific subjects of the user type were returned. However, groups of users, known as usersets, can also be returned from the List Users API. This is done by specifying a relation field in the user_filters request object. Usersets will only expand to the underlying subjects if that type is specified as the user filter object.

Below is an example where usersets can be returned:

model
  schema 1.1

type user

type group
  relations
    define member: [ user ]

type document
  relations
    define viewer: [ group#member ]

With the tuples:

user	relation	object
group:engineering#member	viewer	document:1
group:product#member	viewer	document:1
user:will	member	group:engineering

Then calling the List Users API for document:1 with relation viewer of type group#member will yield the below response. Note that the user:will is not returned, despite being a member of group:engineering#member because the user_filters does not target the user type.

Node.js

const response = await fgaClient.listUsers({
  object: {
    type: "document",
    id: "1"
  },
  user_filters: [{
    type: "group",
    relation: "member"
  }],
  relation: "viewer",
}, {
  authorization_model_id: "01HXHK5D1Z6SCG1SV7M3BVZVCV",
});
// response.users = [{"userset":{"id":"engineering","relation":"member","type":"group"}},{"userset":{"id":"product","relation":"member","type":"group"}}]

Go

options := ClientListUsersOptions{
    AuthorizationModelId: PtrString("01HXHK5D1Z6SCG1SV7M3BVZVCV"),
}

userFilters := []openfga.UserTypeFilter{{ Type:"group",Relation:"member" }}

body := ClientListUsersRequest{
    Object:       openfga.Object{
        Type:    "document",
        Id:      "1",
    },
    Relation:     "viewer",
    UserFilters:   userFilters,
}

data, err := fgaClient.ListUsers(context.Background()).
    Body(body).
    Options(options).
    Execute()

// data.Users = [{"userset":{"id":"engineering","relation":"member","type":"group"}}, {"userset":{"id":"product","relation":"member","type":"group"}}]

.NET

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HXHK5D1Z6SCG1SV7M3BVZVCV",
};
var body = new ClientListUsersRequest {
    Object = new FgaObject {
      Type = "document",
      Id = "1"
    },
    Relation = "viewer",
    UserFilters = new List<UserTypeFilter> {
      new() {
        Type = "group"
        Relation = "member"
        
      }
    }
    
};

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

// response.Users = [{"userset":{"id":"engineering","relation":"member","type":"group"}},{"userset":{"id":"product","relation":"member","type":"group"}}]

Python

  options = {
      "authorization_model_id": "01HXHK5D1Z6SCG1SV7M3BVZVCV"
  }

  userFilters = [
      UserTypeFilter(type="group",relation="member")
  ]

  body = ClientListUsersRequest(
      object=FgaObject(type="document",id="1"),
      relation="viewer",
      user_filters=userFilters,
  )

  response = await fga_client.list_users(body, options)

  # response.users = [{"userset":{"id":"engineering","relation":"member","type":"group"}},{"userset":{"id":"product","relation":"member","type":"group"}}]

Java

var options = new ClientListUsersOptions()
        .authorizationModelId("01HXHK5D1Z6SCG1SV7M3BVZVCV");

var userFilters = new ArrayList<UserTypeFilter>() {
  {
      add(new UserTypeFilter().type("group").relation("member"));
  }
};


var body = new ClientListUsersRequest()
        ._object(new FgaObject().type("document").id("1"))
        .relation("viewer")
        .userFilters(userFilters);

var response = fgaClient.listUsers(body, options).get();

// response.getUsers() = [{"userset":{"id":"engineering","relation":"member","type":"group"}},{"userset":{"id":"product","relation":"member","type":"group"}}]

CLI

fga query list-users --store-id=${FGA_STORE_ID} --model-id=01HXHK5D1Z6SCG1SV7M3BVZVCV --object document:1 --relation viewer --user-filter group#member 

# Response: {"users": [{"userset":{"id":"engineering","relation":"member","type":"group"}}, {"userset":{"id":"product","relation":"member","type":"group"}}]}

curl

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/list-users \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{
        "authorization_model_id": "01HXHK5D1Z6SCG1SV7M3BVZVCV",
        "object": {
          "type: "document",
          "id": "1",
        },
        "relation": "viewer",
        "user_filters": [
          { 
            "type": "group",
            "relation": "member"
          }
        ]
    }'


# Response: {"users": [{"userset":{"id":"engineering","relation":"member","type":"group"}}, {"userset":{"id":"product","relation":"member","type":"group"}}]}

Type-bound public access

The List Users API supports tuples expressing public access via the wildcard syntax (e.g. user:*). Wildcard tuples that satisfy the query criteria will be returned with the wildcard root object property that will specify the type. A typed-bound public access result indicates that the object has a public relation but it doesn't necessarily indicate that all users of that type have that relation, it is possible that exclusions via the but not syntax exists. The API will not expand wildcard results further to any ID'd user object. Further, specific users that have been granted access will be returned in addition to any public access for that user's type.

caution

A List Users response with a type-bound public access result (e.g. user:*) doesn't necessarily indicate that all users of that type have access, it is possible that exclusions exist. It is recommended to perform a Check on specific users to ensure they have access to the target object.

Example response with type-bound public access:

{
  "users": [
    {
      "wildcard": {
        "type": "user"
      }
    },
    {
      "object": {
        "type": "user",
        "id": "anne"
      }
    }
  ]
}

Related Sections

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

OpenFGA List Users API

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

• More