Relationship Queries

Check user authorization

The Check API returns whether a given user has a relationship with a given object in a given store.

The user field of the request can be a specific target, such as user:anne, or a userset (set of users) such as group:marketing#member or a type-bound public access user:*. 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.

A contextual_tuples object may also be included in the body of the request. This object contains one field tuple_keys, which is an array of tuple keys. Each of these tuples may have an associated condition. You may also provide an authorization_model_id in the body. This is used to assert that the input tuple_key is valid for the model specified. If not specified, the assertion is made against the latest authorization model ID.

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

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 be evaluated correctly.

By default, the Check API caches results for a short time to optimize performance. You may specify a value of HIGHER_CONSISTENCY for the optional consistency parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency. The response returns whether the relationship exists in the field allowed.

Some exceptions apply, but in general, if a Check API responds with {allowed: true}, then you can expect the equivalent ListObjects query to return the object, and viceversa. For example, if Check(user:anne, reader, document:2021-budget) responds with {allowed: true}, then ListObjects(user:anne, reader, document) may include document:2021-budget in the response.

Examples

Querying with contextual tuples

In order to check if user user:anne of type user has a reader relationship with object document:2021-budget given the following contextual tuple:

{
  "user": "user:anne",
  "relation": "member",
  "object": "time_slot:office_hours"
}

the Check API can be used with the following request body:

{
  "tuple_key": {
    "user": "user:anne",
    "relation": "reader",
    "object": "document:2021-budget"
  },
  "contextual_tuples": {
    "tuple_keys": [
      {
        "user": "user:anne",
        "relation": "member",
        "object": "time_slot:office_hours"
      }
    ]
  },
  "authorization_model_id": "01G50QVV17PECNVAHX1GG4Y5NC"
}

Querying usersets

Some Checks always return true, even without any tuples. For example, for the following authorization model:

model
  schema 1.1
type user
type document
  relations
    define reader: [user]

the following query:

{
  "tuple_key": {
     "user": "document:2021-budget#reader",
     "relation": "reader",
     "object": "document:2021-budget"
  }
}

always returns { "allowed": true }. This is because usersets are self-defining: the userset document:2021-budget#reader always has the reader relation with document:2021-budget.

Querying usersets with difference in the model

A Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model:

model
  schema 1.1
type user
type group
  relations
    define member: [user]
type document
  relations
    define blocked: [user]
    define reader: [group#member] but not blocked

the following query:

{
  "tuple_key": {
     "user": "group:finance#member",
     "relation": "reader",
     "object": "document:2021-budget"
  },
  "contextual_tuples": {
    "tuple_keys": [
      {
        "user": "user:anne",
        "relation": "member",
        "object": "group:finance"
      },
      {
        "user": "group:finance#member",
        "relation": "reader",
        "object": "document:2021-budget"
      },
      {
        "user": "user:anne",
        "relation": "blocked",
        "object": "document:2021-budget"
      }
    ]
  },
}

returns { "allowed": true }, even though a specific user of the userset group:finance#member does not have the reader relationship with the given object.

Requesting higher consistency

By default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency.

{
  "tuple_key": {
     "user": "group:finance#member",
     "relation": "reader",
     "object": "document:2021-budget"
  },
  "consistency": "HIGHER_CONSISTENCY"
}

POST

stores

{store_id}

check

Node.js

const { OpenFgaClient, ConsistencyPreference } = 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; requests can override this.
});

async function main() {
    const body = {
      "user": "user:anne",
      "relation": "reader",
      "object": "document:budget"
    };
    const options = {
    
    };
    const response = await fgaClient.check(body, options);
}

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

package main

import (
    "context"
    "os"

    . "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"), // Optional; requests can override this.
    })
    if err != nil {
        panic(err)
    }
    
    body := ClientCheckRequest{
      User: "user:anne",
      Relation: "reader",
      Object: "document:budget",
    }
    options := ClientCheckOptions{
    
    }
    data, err := fgaClient.Check(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.Model;
using Environment = System.Environment;

var fgaClient = new OpenFgaClient(new ClientConfiguration() {
  ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
  StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
  AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional; requests can override this.
});

var body = new ClientCheckRequest {
  User = "user:anne",
  Relation = "reader",
  Object = "document:budget",
};
var options = new ClientCheckOptions {

};
var response = await fgaClient.Check(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

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"), # Optional; requests can override this.
    )
    async with OpenFgaClient(configuration) as fga_client:
        body = ClientCheckRequest(
          user="user:anne",
          relation="reader",
          object="document:budget",
        )
        options = {
        
        }
        response = await fga_client.check(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.*;
import dev.openfga.sdk.api.client.model.*;
import dev.openfga.sdk.api.model.*;
import java.util.List;
import java.util.Map;
import java.util.ArrayList;

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")); // Optional; requests can override this.
        var fgaClient = new OpenFgaClient(config);
        
        var body = new ClientCheckRequest()
          .user("user:anne")
          .relation("reader")
          ._object("document:budget");
        var options = new ClientCheckOptions();
        var response = fgaClient.check(body, options).get();
    }
}

# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.

curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/check" \
  -H "content-type: application/json" \
  -d '{
  "authorization_model_id": "'"$FGA_MODEL_ID"'",
  "tuple_key": {
    "user": "user:anne",
    "relation": "reader",
    "object": "document:budget"
  }
}'

{
  "allowed": true,
  "resolution": "<string>"
}

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

{
  "code": "unauthenticated",
  "message": "unauthenticated"
}

{
  "code": "forbidden",
  "message": "the principal is not authorized to perform the action"
}

{
  "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": "internal_error",
  "message": "Internal Server Error"
}

Path Parameters

store_id

string

required

Body

application/json

tuple_key

object

required

Show child attributes

authorization_model_id

string

Example:

"01G5JAVJ41T49E9TT3SKVS7X1J"

consistency

enum<string>

default:UNSPECIFIED

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

Available options:

UNSPECIFIED,

MINIMIZE_LATENCY,

HIGHER_CONSISTENCY

Example:

"MINIMIZE_LATENCY"

context

object

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

contextual_tuples

object

Show child attributes

Response

A successful response.

allowed

boolean

Example:

true

resolution

string

For internal use only.

Last modified on September 28, 2026

⌘I

Node.js

const { OpenFgaClient, ConsistencyPreference } = 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; requests can override this.
});

async function main() {
    const body = {
      "user": "user:anne",
      "relation": "reader",
      "object": "document:budget"
    };
    const options = {
    
    };
    const response = await fgaClient.check(body, options);
}

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

package main

import (
    "context"
    "os"

    . "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"), // Optional; requests can override this.
    })
    if err != nil {
        panic(err)
    }
    
    body := ClientCheckRequest{
      User: "user:anne",
      Relation: "reader",
      Object: "document:budget",
    }
    options := ClientCheckOptions{
    
    }
    data, err := fgaClient.Check(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.Model;
using Environment = System.Environment;

var fgaClient = new OpenFgaClient(new ClientConfiguration() {
  ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
  StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
  AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional; requests can override this.
});

var body = new ClientCheckRequest {
  User = "user:anne",
  Relation = "reader",
  Object = "document:budget",
};
var options = new ClientCheckOptions {

};
var response = await fgaClient.Check(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

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"), # Optional; requests can override this.
    )
    async with OpenFgaClient(configuration) as fga_client:
        body = ClientCheckRequest(
          user="user:anne",
          relation="reader",
          object="document:budget",
        )
        options = {
        
        }
        response = await fga_client.check(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.*;
import dev.openfga.sdk.api.client.model.*;
import dev.openfga.sdk.api.model.*;
import java.util.List;
import java.util.Map;
import java.util.ArrayList;

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")); // Optional; requests can override this.
        var fgaClient = new OpenFgaClient(config);
        
        var body = new ClientCheckRequest()
          .user("user:anne")
          .relation("reader")
          ._object("document:budget");
        var options = new ClientCheckOptions();
        var response = fgaClient.check(body, options).get();
    }
}

# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.

curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/check" \
  -H "content-type: application/json" \
  -d '{
  "authorization_model_id": "'"$FGA_MODEL_ID"'",
  "tuple_key": {
    "user": "user:anne",
    "relation": "reader",
    "object": "document:budget"
  }
}'

{
  "allowed": true,
  "resolution": "<string>"
}

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

{
  "code": "unauthenticated",
  "message": "unauthenticated"
}

{
  "code": "forbidden",
  "message": "the principal is not authorized to perform the action"
}

{
  "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": "internal_error",
  "message": "Internal Server Error"
}

Stores

Authorization Models

Relationship Tuples

Relationship Queries

Assertions

AuthZenService

Check user authorization

Examples

Querying with contextual tuples

Querying usersets

Querying usersets with difference in the model

Requesting higher consistency

Path Parameters

Body

Response