Node.js

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

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL, // https://api.us1.fga.dev, or your store's eu1/au1 region
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID,
  credentials: {
    method: CredentialsMethod.ClientCredentials,
    config: {
      apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER, // auth.fga.dev
      apiAudience: process.env.FGA_API_AUDIENCE, // URL for your store's region
      clientId: process.env.FGA_CLIENT_ID,
      clientSecret: process.env.FGA_CLIENT_SECRET,
    },
  },
});

async function main() {
  const body = {
    "object": {"type": "document", "id": "budget"},
    "relation": "reader",
    "user_filters": [
      {
        "type": "user"
      }
    ]
  };
  const options = {

  };
  const response = await fgaClient.listUsers(body, options);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

package main

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

// Configure FGA_API_URL and FGA_API_AUDIENCE for your store's us1/eu1/au1 region.
// Set FGA_STORE_ID, FGA_MODEL_ID, FGA_API_TOKEN_ISSUER, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
            ApiUrl: os.Getenv("FGA_API_URL"),
            StoreId: os.Getenv("FGA_STORE_ID"),
            AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
            Credentials: &credentials.Credentials{
                Method: credentials.CredentialsMethodClientCredentials,
                Config: &credentials.Config{
                    ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
                    ClientCredentialsApiAudience: os.Getenv("FGA_API_AUDIENCE"),
                    ClientCredentialsClientId: os.Getenv("FGA_CLIENT_ID"),
                    ClientCredentialsClientSecret: os.Getenv("FGA_CLIENT_SECRET"),
                },
            },
        })
        if err != nil { panic(err) }

    body := ClientListUsersRequest{
      Object: openfga.FgaObject{
        Type: "document",
        Id: "budget",
      },
      Relation: "reader",
      UserFilters: []openfga.UserTypeFilter{
        openfga.UserTypeFilter{
          Type: "user",
        },
      },
    }
    options := ClientListUsersOptions{

    }
    data, err := fgaClient.ListUsers(context.Background()).Body(body).Options(options).Execute()
    if err != nil {
        panic(err)
    }
    _ = data
}

using System.Collections.Generic;
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Configuration;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

// FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.
var fgaClient = new OpenFgaClient(new ClientConfiguration() {
  ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
  StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
  AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
  Credentials = new Credentials() {
    Method = CredentialsMethod.ClientCredentials,
    Config = new CredentialsConfig() {
      ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
      ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
      ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
      ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
    }
  }
});

var body = new ClientListUsersRequest {
  Object = new FgaObject {
    Type = "document",
    Id = "budget",
  },
  Relation = "reader",
  UserFilters = new List<UserTypeFilter> {
    new UserTypeFilter {
      Type = "user",
    },
  },
};
var options = new ClientListUsersOptions {

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

import asyncio
import os
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.client.models import ClientTuple
from openfga_sdk.models import RelationshipCondition, FgaObject, UserTypeFilter
from openfga_sdk.client.models.list_users_request import ClientListUsersRequest
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.
credentials = Credentials(
    method='client_credentials',
    configuration=CredentialConfiguration(
        api_issuer=os.environ.get('FGA_API_TOKEN_ISSUER'),
        api_audience=os.environ.get('FGA_API_AUDIENCE'),
        client_id=os.environ.get('FGA_CLIENT_ID'),
        client_secret=os.environ.get('FGA_CLIENT_SECRET'),
    ),
)

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'),
        credentials=credentials,
    )
    async with OpenFgaClient(configuration) as fga_client:
        body = ClientListUsersRequest(
          object=FgaObject(
            type="document",
            id="budget",
          ),
          relation="reader",
          user_filters=[
            UserTypeFilter(
              type="user",
            )
          ],
        )
        options = {

        }
        response = await fga_client.list_users(body, options)

asyncio.run(main())

import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import dev.openfga.sdk.api.configuration.ClientCredentials;
import dev.openfga.sdk.api.configuration.Credentials;
import dev.openfga.sdk.api.configuration.ClientCheckOptions;
import dev.openfga.sdk.api.configuration.ClientBatchCheckOptions;
import dev.openfga.sdk.api.configuration.ClientWriteOptions;
import dev.openfga.sdk.api.configuration.ClientListObjectsOptions;
import dev.openfga.sdk.api.configuration.ClientListUsersOptions;
import dev.openfga.sdk.api.client.model.*;
import dev.openfga.sdk.api.model.*;
import java.util.List;
import java.util.Map;

// FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.
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_MODEL_ID"))
            .credentials(new Credentials(new ClientCredentials()
                .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
                .apiAudience(System.getenv("FGA_API_AUDIENCE"))
                .clientId(System.getenv("FGA_CLIENT_ID"))
                .clientSecret(System.getenv("FGA_CLIENT_SECRET"))));
        var fgaClient = new OpenFgaClient(config);

        var body = new ClientListUsersRequest()
          ._object(new FgaObject()
            .type("document")
            .id("budget"))
          .relation("reader")
          .userFilters(java.util.Arrays.asList(new UserTypeFilter()
            .type("user")));
        var options = new ClientListUsersOptions();
        var response = fgaClient.listUsers(body, options).get();
    }
}

# Set FGA_API_URL to your store region (https://api.us1.fga.dev, or eu1/au1).
# Set FGA_STORE_ID and obtain FGA_BEARER_TOKEN with the client credentials grant.
# See /integration/getting-your-api-keys; never put client secrets in source code.

curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/list-users" \
  -H "authorization: Bearer $FGA_BEARER_TOKEN" \
  -H "content-type: application/json" \
  -d '{
  "object": {
    "type": "document",
    "id": "budget"
  },
  "relation": "reader",
  "user_filters": [
    {
      "type": "user"
    }
  ]
}'

{
  "users": [
    {
      "object": {
        "id": "0bcdf6fa-a6aa-4730-a8eb-9cf172ff16d9",
        "type": "document"
      },
      "userset": {
        "id": "fga",
        "relation": "member",
        "type": "group"
      },
      "wildcard": {
        "type": "employee"
      }
    }
  ]
}

{
  "code": "validation_error",
  "message": "Generic validation error"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "undefined_endpoint",
  "message": "Endpoint not enabled"
}

{
  "code": "10",
  "message": "transaction conflict"
}

{
  "code": "throttled_timeout_error",
  "message": "timeout due to throttling on complex request"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate Limit exceeded"
}

{
  "code": "internal_error",
  "message": "Internal Server Error"
}

Relationship Queries

List users related to an object

The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.

To arrive at a result, the API uses:

An authorization model
Explicit tuples written through the Write API
Contextual tuples present in the request
Implicit tuples that exist by virtue of applying set theory

For example: document:2021-budget#viewer@document:2021-budget#viewer. In this example, the set of users who are viewers of document:2021-budget are the set of users who are the viewers of document:2021-budget.

An authorization_model_id may be specified in the body. If it is not specified, the latest authorization model ID is used.

Note: We recommend you specify an authorization model ID for better performance.

You may also specify contextual_tuples that are treated as regular tuples. Each of these tuples may have an associated condition.

You may also provide a context object that is used to evaluate the conditioned tuples in the system.

Note: We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples are evaluated correctly.

The response contains the related users in an array in the “users” field of the response. These results may include specific objects, usersets or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.

In cases where a type-bound public access result is returned (e.g. user:*), it cannot be inferred that all subjects of that type have a relation to the object; it is possible that negations exist and checks should still be queried on individual subjects to ensure access to that document.

The number of users in the response array is at most 250, and is limited by an execution timeout of 3 seconds, whichever is hit first. The users given are not sorted, and therefore two identical calls can give a different set of users.

POST

stores

{store_id}

list-users

Node.js

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

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL, // https://api.us1.fga.dev, or your store's eu1/au1 region
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID,
  credentials: {
    method: CredentialsMethod.ClientCredentials,
    config: {
      apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER, // auth.fga.dev
      apiAudience: process.env.FGA_API_AUDIENCE, // URL for your store's region
      clientId: process.env.FGA_CLIENT_ID,
      clientSecret: process.env.FGA_CLIENT_SECRET,
    },
  },
});

async function main() {
  const body = {
    "object": {"type": "document", "id": "budget"},
    "relation": "reader",
    "user_filters": [
      {
        "type": "user"
      }
    ]
  };
  const options = {

  };
  const response = await fgaClient.listUsers(body, options);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

package main

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

// Configure FGA_API_URL and FGA_API_AUDIENCE for your store's us1/eu1/au1 region.
// Set FGA_STORE_ID, FGA_MODEL_ID, FGA_API_TOKEN_ISSUER, FGA_CLIENT_ID, and FGA_CLIENT_SECRET.
func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
            ApiUrl: os.Getenv("FGA_API_URL"),
            StoreId: os.Getenv("FGA_STORE_ID"),
            AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
            Credentials: &credentials.Credentials{
                Method: credentials.CredentialsMethodClientCredentials,
                Config: &credentials.Config{
                    ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
                    ClientCredentialsApiAudience: os.Getenv("FGA_API_AUDIENCE"),
                    ClientCredentialsClientId: os.Getenv("FGA_CLIENT_ID"),
                    ClientCredentialsClientSecret: os.Getenv("FGA_CLIENT_SECRET"),
                },
            },
        })
        if err != nil { panic(err) }

    body := ClientListUsersRequest{
      Object: openfga.FgaObject{
        Type: "document",
        Id: "budget",
      },
      Relation: "reader",
      UserFilters: []openfga.UserTypeFilter{
        openfga.UserTypeFilter{
          Type: "user",
        },
      },
    }
    options := ClientListUsersOptions{

    }
    data, err := fgaClient.ListUsers(context.Background()).Body(body).Options(options).Execute()
    if err != nil {
        panic(err)
    }
    _ = data
}

using System.Collections.Generic;
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Configuration;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

// FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.
var fgaClient = new OpenFgaClient(new ClientConfiguration() {
  ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
  StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
  AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
  Credentials = new Credentials() {
    Method = CredentialsMethod.ClientCredentials,
    Config = new CredentialsConfig() {
      ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
      ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
      ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
      ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
    }
  }
});

var body = new ClientListUsersRequest {
  Object = new FgaObject {
    Type = "document",
    Id = "budget",
  },
  Relation = "reader",
  UserFilters = new List<UserTypeFilter> {
    new UserTypeFilter {
      Type = "user",
    },
  },
};
var options = new ClientListUsersOptions {

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

import asyncio
import os
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.client.models import ClientTuple
from openfga_sdk.models import RelationshipCondition, FgaObject, UserTypeFilter
from openfga_sdk.client.models.list_users_request import ClientListUsersRequest
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.
credentials = Credentials(
    method='client_credentials',
    configuration=CredentialConfiguration(
        api_issuer=os.environ.get('FGA_API_TOKEN_ISSUER'),
        api_audience=os.environ.get('FGA_API_AUDIENCE'),
        client_id=os.environ.get('FGA_CLIENT_ID'),
        client_secret=os.environ.get('FGA_CLIENT_SECRET'),
    ),
)

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'),
        credentials=credentials,
    )
    async with OpenFgaClient(configuration) as fga_client:
        body = ClientListUsersRequest(
          object=FgaObject(
            type="document",
            id="budget",
          ),
          relation="reader",
          user_filters=[
            UserTypeFilter(
              type="user",
            )
          ],
        )
        options = {

        }
        response = await fga_client.list_users(body, options)

asyncio.run(main())

import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import dev.openfga.sdk.api.configuration.ClientCredentials;
import dev.openfga.sdk.api.configuration.Credentials;
import dev.openfga.sdk.api.configuration.ClientCheckOptions;
import dev.openfga.sdk.api.configuration.ClientBatchCheckOptions;
import dev.openfga.sdk.api.configuration.ClientWriteOptions;
import dev.openfga.sdk.api.configuration.ClientListObjectsOptions;
import dev.openfga.sdk.api.configuration.ClientListUsersOptions;
import dev.openfga.sdk.api.client.model.*;
import dev.openfga.sdk.api.model.*;
import java.util.List;
import java.util.Map;

// FGA_API_URL and FGA_API_AUDIENCE must match the store's us1/eu1/au1 region.
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_MODEL_ID"))
            .credentials(new Credentials(new ClientCredentials()
                .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
                .apiAudience(System.getenv("FGA_API_AUDIENCE"))
                .clientId(System.getenv("FGA_CLIENT_ID"))
                .clientSecret(System.getenv("FGA_CLIENT_SECRET"))));
        var fgaClient = new OpenFgaClient(config);

        var body = new ClientListUsersRequest()
          ._object(new FgaObject()
            .type("document")
            .id("budget"))
          .relation("reader")
          .userFilters(java.util.Arrays.asList(new UserTypeFilter()
            .type("user")));
        var options = new ClientListUsersOptions();
        var response = fgaClient.listUsers(body, options).get();
    }
}

# Set FGA_API_URL to your store region (https://api.us1.fga.dev, or eu1/au1).
# Set FGA_STORE_ID and obtain FGA_BEARER_TOKEN with the client credentials grant.
# See /integration/getting-your-api-keys; never put client secrets in source code.

curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/list-users" \
  -H "authorization: Bearer $FGA_BEARER_TOKEN" \
  -H "content-type: application/json" \
  -d '{
  "object": {
    "type": "document",
    "id": "budget"
  },
  "relation": "reader",
  "user_filters": [
    {
      "type": "user"
    }
  ]
}'

{
  "users": [
    {
      "object": {
        "id": "0bcdf6fa-a6aa-4730-a8eb-9cf172ff16d9",
        "type": "document"
      },
      "userset": {
        "id": "fga",
        "relation": "member",
        "type": "group"
      },
      "wildcard": {
        "type": "employee"
      }
    }
  ]
}

{
  "code": "validation_error",
  "message": "Generic validation error"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "undefined_endpoint",
  "message": "Endpoint not enabled"
}

{
  "code": "10",
  "message": "transaction conflict"
}

{
  "code": "throttled_timeout_error",
  "message": "timeout due to throttling on complex request"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate Limit exceeded"
}

{
  "code": "internal_error",
  "message": "Internal Server Error"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Scopes

list:users

Allows reading results of list users

Path Parameters

store_id

string

required

Body

application/json

object

required

Object represents an OpenFGA Object.

An Object is composed of a type and identifier (e.g. 'document:1')

See https://openfga.dev/docs/concepts#what-is-an-object

Show child attributes

Example:

"document:example"

relation

string

required

Example:

"reader"

user_filters

object[]

required

The type of results returned. Only accepts exactly one value.

Required array length: 1 element

Show child attributes

Example:

[
  { "type": "user" },
  { "relation": "member", "type": "group" }
]

authorization_model_id

string

Example:

"01G5JAVJ41T49E9TT3SKVS7X1J"

consistency

enum<string>

default:UNSPECIFIED

Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY.

Available options:

UNSPECIFIED,

MINIMIZE_LATENCY,

HIGHER_CONSISTENCY

Example:

"MINIMIZE_LATENCY"

context

object

Additional request context that will be used to evaluate any ABAC conditions encountered in the query evaluation.

contextual_tuples

object[]

Maximum array length: 100

Show child attributes

Response

A successful response.

users

object[]

required

Show child attributes

Overview

Assertions

Authorization Models

Relationship Queries

Relationship Tuples

Permissions Index

Logs

List users related to an object

Authorizations

Scopes

Path Parameters

Body

Response