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 = {
"user": "user:anne",
"relation": "reader",
"object": "document:budget"
};
const options = {"pageSize":20};
const response = await fgaClient.read(body, options);
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});package main
import (
"context"
"os"
. "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) }
pageSize := int32(20)
user := "user:anne"
relation := "reader"
object := "document:budget"
body := ClientReadRequest{
User: &user,
Relation: &relation,
Object: &object,
}
options := ClientReadOptions{
PageSize: &pageSize,
}
response, err := fgaClient.Read(context.Background()).Body(body).Options(options).Execute()
if err != nil {
panic(err)
}
_ = response
}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 ClientReadRequest {
User = "user:anne",
Relation = "reader",
Object = "document:budget",
};
var options = new ClientReadOptions {
PageSize = 20,
};
var response = await fgaClient.Read(body, options);import asyncio
import os
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.client.models import ClientCheckRequest, ClientTuple
from openfga_sdk.models import RelationshipCondition
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'),
),
)
from openfga_sdk 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'),
credentials=credentials,
)
async with OpenFgaClient(configuration) as fga_client:
body = ReadRequestTupleKey(
user="user:anne",
relation="reader",
object="document:budget",
)
options = {"page_size": 20}
response = await fga_client.read(body=body, options=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.
import dev.openfga.sdk.api.configuration.ClientReadOptions;
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 ClientReadRequest()
.user("user:anne")
.relation("reader")
._object("document:budget");
var options = new ClientReadOptions()
.pageSize(20);
var response = fgaClient.read(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/read" \
-H "authorization: Bearer $FGA_BEARER_TOKEN" \
-H "content-type: application/json" \
-d '{
"tuple_key": {
"user": "user:anne",
"relation": "reader",
"object": "document:budget"
},
"page_size": 20
}'{
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==",
"tuples": [
{
"key": {
"object": "document:2021-budget",
"relation": "reader",
"user": "user:anne",
"condition": {
"name": "condition1",
"context": {}
}
},
"timestamp": "2023-11-07T05:31:56Z"
}
]
}{
"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"
}Get tuples from the store that matches a query, without following userset rewrite rules
The Read API will return the tuples for a certain store that match a query filter specified in the body of the request.
The API doesn’t guarantee order by any field.
It is different from the /stores/{store_id}/expand API in that it only returns relationship tuples that are stored in the system and satisfy the query.
In the body:
tuple_keyis optional. If not specified, it will return all tuples in the store.tuple_key.objectis mandatory iftuple_keyis specified. It can be a full object (e.g.,type:object_id) or type only (e.g.,type:).tuple_key.useris mandatory if tuple_key is specified in the case thetuple_key.objectis a type only.
Examples
Query for all objects in a type definition
To query for all objects that user:bob has reader relationship in the document type definition, call Read API with body of
{
"tuple_key": {
"user": "user:bob",
"relation": "reader",
"object": "document:"
}
}
The API will return tuples and a continuation token, something like
{
"tuples": [
{
"key": {
"user": "user:bob",
"relation": "reader",
"object": "document:2021-budget"
},
"timestamp": "2021-10-06T15:32:11.128Z"
}
],
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
This means that user:bob has a reader relationship with 1 document document:2021-budget. Note that this API, unlike the List Objects API, does not evaluate the tuples in the store.
The continuation token will be empty if there are no more tuples to query.
Query for all stored relationship tuples that have a particular relation and object
To query for all users that have reader relationship with document:2021-budget, call Read API with body of
{
"tuple_key": {
"object": "document:2021-budget",
"relation": "reader"
}
}
The API will return something like
{
"tuples": [
{
"key": {
"user": "user:bob",
"relation": "reader",
"object": "document:2021-budget"
},
"timestamp": "2021-10-06T15:32:11.128Z"
}
],
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
This means that document:2021-budget has 1 reader (user:bob). Note that, even if the model said that all writers are also readers, the API will not return writers such as user:anne because it only returns tuples and does not evaluate them.
Query for all users with all relationships for a particular document
To query for all users that have any relationship with document:2021-budget, call Read API with body of
{
"tuple_key": {
"object": "document:2021-budget"
}
}
The API will return something like
{
"tuples": [
{
"key": {
"user": "user:anne",
"relation": "writer",
"object": "document:2021-budget"
},
"timestamp": "2021-10-05T13:42:12.356Z"
},
{
"key": {
"user": "user:bob",
"relation": "reader",
"object": "document:2021-budget"
},
"timestamp": "2021-10-06T15:32:11.128Z"
}
],
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
This means that document:2021-budget has 1 reader (user:bob) and 1 writer (user:anne).
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 = {
"user": "user:anne",
"relation": "reader",
"object": "document:budget"
};
const options = {"pageSize":20};
const response = await fgaClient.read(body, options);
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});package main
import (
"context"
"os"
. "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) }
pageSize := int32(20)
user := "user:anne"
relation := "reader"
object := "document:budget"
body := ClientReadRequest{
User: &user,
Relation: &relation,
Object: &object,
}
options := ClientReadOptions{
PageSize: &pageSize,
}
response, err := fgaClient.Read(context.Background()).Body(body).Options(options).Execute()
if err != nil {
panic(err)
}
_ = response
}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 ClientReadRequest {
User = "user:anne",
Relation = "reader",
Object = "document:budget",
};
var options = new ClientReadOptions {
PageSize = 20,
};
var response = await fgaClient.Read(body, options);import asyncio
import os
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.client.models import ClientCheckRequest, ClientTuple
from openfga_sdk.models import RelationshipCondition
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'),
),
)
from openfga_sdk 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'),
credentials=credentials,
)
async with OpenFgaClient(configuration) as fga_client:
body = ReadRequestTupleKey(
user="user:anne",
relation="reader",
object="document:budget",
)
options = {"page_size": 20}
response = await fga_client.read(body=body, options=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.
import dev.openfga.sdk.api.configuration.ClientReadOptions;
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 ClientReadRequest()
.user("user:anne")
.relation("reader")
._object("document:budget");
var options = new ClientReadOptions()
.pageSize(20);
var response = fgaClient.read(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/read" \
-H "authorization: Bearer $FGA_BEARER_TOKEN" \
-H "content-type: application/json" \
-d '{
"tuple_key": {
"user": "user:anne",
"relation": "reader",
"object": "document:budget"
},
"page_size": 20
}'{
"continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==",
"tuples": [
{
"key": {
"object": "document:2021-budget",
"relation": "reader",
"user": "user:anne",
"condition": {
"name": "condition1",
"context": {}
}
},
"timestamp": "2023-11-07T05:31:56Z"
}
]
}{
"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
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
Body
Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY.
UNSPECIFIED, MINIMIZE_LATENCY, HIGHER_CONSISTENCY "MINIMIZE_LATENCY"
"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
1 <= x <= 10050
Show child attributes
Show child attributes