Skip to main content

How To Update Relationship Tuples

This is an introduction to adding and deleting relationship tuples.

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.
  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 add user user:anne to have relationship reader with object document:Z

{
  user: 'user:anne',
  relation: 'reader',
  object: 'document:Z'
}

01. Configure the Auth0 FGA API client​

Before calling the write 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 write API to add new relationship tuples​

To add the relationship tuples, we can invoke the write API.


const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
};

await fgaClient.write({
  writes: [
      {"user":"user:anne","relation":"reader","object":"document:Z"}
  ],
}, options);

03. Calling write API to delete relationship tuples​

To delete relationship tuples, we can invoke the write API.

Assume that you want to delete user user:anne's reader relationship with object document:Z

{
  user: 'user:anne',
  relation: 'reader',
  object: 'document:Z'
}

const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
};

await fgaClient.write({
  deletes: [
      { user: 'user:anne', relation: 'reader', object: 'document:Z'}
  ],
}, options);

04. Writing and deleting relationship tuples in the same request​

You can combine both writes and deletes in a single transactional API request. This is useful when you need to update multiple relationships atomically. All operations in the request will either succeed together or fail together.

The Write API allows you to send up to 100 unique tuples in the request. (This limit applies to the sum of both writes and deletes in that request).

For example, you might want to remove user:anne as a writer of document:Z while simultaneously updating user:anne as an reader of document:Z:


const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
};

await fgaClient.write({
  writes: [
      {"user":"user:anne","relation":"reader","object":"document:Z"}
  ],
  deletes: [
      { user: 'user:anne', relation: 'writer', object: 'document:Z'}
  ],
}, options);

This approach ensures that both operations succeed or fail together, maintaining transactional data consistency.

note

When using the Write API, you cannot include the same tuple (same user, relation, and object) in the writes or deletes arrays within a single request. The API will return an error with code cannot_allow_duplicate_tuples_in_one_request if detected.

05. Ignoring duplicate or missing tuples​

Sometimes you might need to write a tuple that already exists, which would normally cause the whole request to fail. You can use the on_duplicate: "ignore" parameter to handle this gracefully.

This is particularly useful for high-volume data imports, migrations, or ensuring certain permissions exist without complex error handling logic.

For example, if you want to ensure user:anne has reader access to document:Z without worrying about whether the relationship already exists in Auth0 FGA:


const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
  conflict: {
    onDuplicateWrites: OnDuplicateWrites.Ignore,
  }
};

await fgaClient.write({
  writes: [
      {"user":"user:anne","relation":"reader","object":"document:Z"}
  ],
}, options);

Similarly, you can use on_missing: "ignore" when deleting tuples that might not exist.


const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
  conflict: {
    onMissingDeletes: OnMissingDeletes.Ignore
  }
};

await fgaClient.write({
  deletes: [
      { user: 'user:anne', relation: 'writer', object: 'document:Z'}
  ],
}, options);

The behavior of on_duplicate: "ignore" is more nuanced for tuples with conditions.

  • Identical Tuples: If a tuple in the request is identical to an existing tuple (same user, relation, object, condition name, and condition context), it will be safely ignored.
  • Conflicting Tuples: If a tuple key (user, relation, object) matches an existing tuple, but the condition name or parameters are different, this is a conflict. The write attempt will be rejected, and the entire transaction will fail with a 409 Conflict error.
Check the following sections for more on how to write your authorization data
Write API

Learn more about the Write API options.

Managing User Access

Learn about how to give a user access to a particular object.

Managing Group Access

Learn about how to give a group of users access to a particular object.

Transactional Writes

Learn about how to update multiple relations within the same API call.

Have Feedback?

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