Before You Start
- Node.js
- Go
- .NET
- Python
- Java
- CLI
- curl
- 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.
- You have installed the SDK.
- You have configured the authorization model and updated the relationship tuples.
- You have loaded
FGA_STORE_IDandFGA_API_URLas environment variables.
Step by step
Consider the following model which includes auser that can have a reader relationship with a document:
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
- Go
- .NET
- Python
- Java
- CLI
- curl
02. Calling List Users API
To return all users of typeuser that have have the reader relationship with document:planning:
The result user:anne and user:beth are the user objects that have the reader relationship with document:planning.
Usersets
In the above example, only specific subjects of theuser 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:
With the tuples:
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.
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.
Example response with type-bound public access:
Related Sections
Take a look at the following section for more on how to perform list users in your systemOpenFGA List Users API
Read the List Users API documentation and see how it works.