Skip to main content

How To 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. You have obtained the necessary environment variables: `FGA_API_URL`, `FGA_STORE_ID`, `FGA_API_TOKEN_ISSUER`, `FGA_API_AUDIENCE`, `FGA_CLIENT_ID` and `FGA_CLIENT_SECRET`.
  2. You have installed the SDK.
  3. You have configured the authorization model and updated the relationship tuples.
  4. You have loaded FGA_API_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET 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 Auth0 FGA API client​

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

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

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

const fgaClient = new OpenFgaClient({
    apiUrl: process.env.FGA_API_URL,
    storeId: process.env.FGA_STORE_ID,
    authorizationModelId: process.env.FGA_MODEL_ID,
    credentials: { // Credentials are not needed if connecting to the Playground API
      method: CredentialsMethod.ClientCredentials,
      config: {
        apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER,
        apiAudience: process.env.FGA_API_AUDIENCE,
        clientId: process.env.FGA_CLIENT_ID,
        clientSecret: process.env.FGA_CLIENT_SECRET,
      },
    },
});

02. Calling Check API​

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


// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'reader',
    object: 'document:Z',
  }, {
    authorizationModelId: '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 BatchCheck 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

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
  • if you pass in more checks than the server supports in a single call (50), the SDK will automatically split and batch the BatchCheck requests for you, how it does this can be configured using the maxBatchSize and maxParallelRequests options in the SDK.

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

const body = {
  checks: [
    {
      user: 'user:anne',
      relation: 'writer',
      object: 'document:Z',
      correlationId: '886224f6-04ae-4b13-bd8e-559c7d3754e1'
    },{
      user: 'user:anne',
      relation: 'reader',
      object: 'document:Z',
      correlationId: 'da452239-a4e0-4791-b5d1-fb3d451ac078'
    }
  ],
}

const options = {
  authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
  maxBatchSize: 50, // optional, default is 50, can be used to limit the number of checks in a single server request
  maxParallelRequests: 10, // optional, default is 10, can be used to limit the parallelization of the BatchCheck chunks
};
const { result } = await fgaClient.batchCheck(body, options);

/*
{
  "results": [
    {
      "correlationId": '886224f6-04ae-4b13-bd8e-559c7d3754e1',
      "allowed": false,
      "request": {
        "user": 'user:anne',
        "relation": 'writer',
        "object": 'document:Z'}
    }, {
      "correlationId": 'da452239-a4e0-4791-b5d1-fb3d451ac078',
      "allowed": true,
      "request": {
        "user": 'user:anne',
        "relation": 'reader',
        "object": 'document:Z'}
    }
  ],
}
*/

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.

Take a look at the following section for more on how to perform authorization checks in your system
Auth0 FGA Check API

Read the Check API documentation and see how it works.

Auth0 FGA Batch Check API

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

Have Feedback?

You can use any of our support channels for any questions or suggestions you may have.