Skip to main content

How to get tuple changes

This section illustrates how to call the Read Changes API to get the list of relationship tuple changes that happened in your store, in the exact order that they happened. The API response includes tuples that have been added or removed in your store. It does not include other changes, like updates to your authorization model and adding new assertions.

Before you start

  1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
  2. You have installed the SDK.
  3. You have configured the authorization model and added some relationship tuples.
  4. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

Step By Step

To get a chronologically ordered list of tuples that have been written or deleted in your store, you can do so by calling the Read Changes API.

01. Configure The OpenFGA API Client

First 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. Get Changes For All Object Types

To get a paginated list of changes that happened in your store:

var type = "";
var continuationToken = "";
var pageSize = 25;

await fgaClient.readChanges({ type }, { pageSize, continuationToken });

The result will contain an array of up to 25 tuples, with the operation (write or delete), and the timestamp in which that operation took place. The result will also contain a continuation token. Save the continuation token in persistent storage between calls so that it is not lost and you do not have to restart from scratch on system restart or on error.

You can then use this token to get the next set of changes:

var type = "";
var continuationToken = "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==";
var pageSize = 25;

await fgaClient.readChanges({ type }, { pageSize, continuationToken });

Once there are no more changes to retrieve, the API will return the same token as the one you sent. Save the token in persistent storage to use at a later time.

note
  • The default page size is 50. The maximum page size allowed is 100.
  • The API response will not return all the changes immediately. There will be a delay of one minute between the time that you add or delete a tuple and the time that you see it in the Read Changes API response.
  • The API response does not expand the tuples. If you wrote a tuple that includes a userset, like {"user": "group:abc#member", "relation": "owner": "doc:budget"}, the Read Changes API will return that exact tuple.

03. Get Changes For A Specific Object Type

Imagine you have the following authorization model:

model
schema 1.1

type user

type group
relations
define member: [user]

type folder
relations
define owner: [group#member, user]

type doc
relations
define owner: [group#member, user]

It is possible to get a list of changes that happened in your store that relate only to one specific object type, like folder, by issuing a call like this:

var type = "folder";
var continuationToken = "";
var pageSize = 25;

await fgaClient.readChanges({ type }, { pageSize, continuationToken });

The response will include a continuation token. In subsequent calls, you have to include the token and the type. (If you send this continuation token without the type parameter set, you will get an error).

var type = "folder";
var continuationToken = "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==";
var pageSize = 25;

await fgaClient.readChanges({ type }, { pageSize, continuationToken });