Skip to main content

Perform a Check

This section will illustrate how to perform a check request to determine whether a user has a certain relationship with an object.

Before you start

  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.

Step by step

Assume that you want to check whether user anne has relationship reader with object document:Z

01. Configure the OpenFGA API client

Before calling the check API, you will need to configure the API client.

// 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
});

02. Calling Check API

To check whether user user:anne has relationship can_view with object document:Z


// Run a check
const { allowed } = await fgaClient.check({
user: 'user:anne',
relation: 'can_view',
object: 'document:Z',
}, {
authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

The result's allowed field will return true if the relationship exists and false if the relationship does not exist.

03. Calling Batch Check API

If you want to check multiple user-object-relationship combinations in a single request, you can use the Batch Check API endpoint. Batching authorization checks together in a single request significantly reduces overall network latency.

The Batch Check endpoint requires a correlation_id parameter for each check. The correlation_id is used to "correlate" the check responses with the checks sent in the request, since tuple_keys and contextual_tuples are not returned in the response on purpose to reduce data transfer to improve network latency. A correlation_id can be composed of any string of alphanumeric characters or dashes between 1-36 characters in length. This means you can use:

  • simple iterating integers 1,2,3,etc
  • UUID e5fe049b-f252-40b3-b795-fe485d588279
  • ULID 01JBMD9YG0XH3B4GVA8A9D2PSN
  • or some other unique string

But each correlation_id within a request must be unique.

Note: If you are using one of our SDKs, the correlation_id is inserted for you by default and automatically correlates the allowed response with the proper tuple_key.

To check whether user user:anne has multiple relationships writer and reader with object document:Z

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/batch-check \
-H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
-H "content-type: application/json" \
-d '{
"authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA",
"checks": [
{
"tuple_key": {
"user":"user:anne",
"relation":"writer",
"object":"document:Z",
},
"correlation_id": "886224f6-04ae-4b13-bd8e-559c7d3754e1"
},
{
"tuple_key": {
"user":"user:anne",
"relation":"reader",
"object":"document:Z",
},
"correlation_id": "da452239-a4e0-4791-b5d1-fb3d451ac078"
},


# Response:
{
"results": {
{ "886224f6-04ae-4b13-bd8e-559c7d3754e1": { "allowed": false }}, # writer
{ "da452239-a4e0-4791-b5d1-fb3d451ac078": { "allowed": true }}, # reader

}
}

The result will include an allowed field for each authorization check that will return true if the relationship exists and false if the relationship does not exist.

Configuring Batch Check

BatchCheck has two available configuration options:

  1. Limit the number of checks allowed in a single BatchCheck request.

    • Environment variable: OPENFGA_MAX_CHECKS_PER_BATCH_CHECK
    • Command line flag: --max-checks-per-batch-check
    • If more items are received in a single request than allowed by this limit, the API will return an error.
  2. Limit the number of Checks which can be resolved concurrently

    • Environment variable: OPENFGA_MAX_CONCURRENT_CHECKS_PER_BATCH_CHECK
    • Command line flag: --max-concurrent-checks-per-batch-check
OpenFGA Check API

Read the Check API documentation and see how it works.

OpenFGA Batch Check API

Read the Batch Check API documentation and see how it works.