How To Update Relationship Tuples

This section will illustrate how to update relationship tuples.

Before You Start

Node.js

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

Go

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

.NET

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

Python

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model.
4. You have loaded FGA_API_SCHEME, FGA_API_HOST, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

Java

1. You have obtained the environment, store id, client id and 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.

CLI

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the CLI.
3. You have configured the authorization model.
4. You have loaded FGA_SERVER_URL, FGA_STORE_ID, FGA_API_TOKEN_ISSUER, FGA_API_AUDIENCE, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

curl

1. You have obtained the environment, store id, client id and client secret.
2. You have configured the authorization model.
3. You have loaded FGA_STORE_ID and FGA_SERVER_URL 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 Okta FGA API Client

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

Node.js

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 = 'fga.us.auth0.com'
// 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,
      },
    },
});

Go

import (
    "os"

    openfga "github.com/openfga/go-sdk"
    . "github.com/openfga/go-sdk/client"
    "github.com/openfga/go-sdk/credentials"
)

// 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 = 'fga.us.auth0.com'
// 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

func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), 
        StoreId:              os.Getenv("FGA_STORE_ID"),
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
        Credentials: &credentials.Credentials{ // Credentials are not needed if connecting to the Playground API
            Method: credentials.CredentialsMethodClientCredentials,
            Config: &credentials.Config{
                ClientCredentialsClientId:       os.Getenv("FGA_CLIENT_ID"),
                ClientCredentialsClientSecret:   os.Getenv("FGA_CLIENT_SECRET"),
                ClientCredentialsApiAudience:    os.Getenv("FGA_API_AUDIENCE"),
                ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
            },
        },
    })

    if err != nil {
        // .. Handle error
    }
}

.NET

using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

// 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 = 'fga.us.auth0.com'
// 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

class MyProgram {
    static async Task Main() {
        var configuration = new ClientConfiguration() {
            ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
            StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
            AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
            Credentials = new Credentials() { // Credentials are not needed if connecting to the Playground API
                Method = CredentialsMethod.ClientCredentials,
                Config = new CredentialsConfig() {
                    ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
                    ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
                    ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
                    ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
                }
            }
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

Python

import os
import openfga_sdk
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# 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 = 'fga.us.auth0.com'
# 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

async def main():
    credentials = Credentials(
      method='client_credentials',
      configuration=CredentialConfiguration(
          api_issuer= os.environ.get('FGA_API_TOKEN_ISSUER'),
          api_audience= os.environ.get('FGA_API_AUDIENCE'),
          client_id= os.environ.get('FGA_CLIENT_ID'),
          client_secret= os.environ.get('FGA_CLIENT_SECRET'),
      )
    )

    configuration = ClientConfiguration(
        api_url = os.environ.get('FGA_API_URL'), # required, e.g. https://api.fga.example
        store_id = os.environ.get('FGA_STORE_ID'), # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        authorization_model_id = os.environ.get('FGA_MODEL_ID'), # Optional, can be overridden per request
    )

    # Enter a context with an instance of the OpenFgaClient
    async with OpenFgaClient(configuration) as fga_client:
        api_response = await fga_client.read_authorization_models()
        await fga_client.close()

asyncio.run(main())

Java

import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import dev.openfga.sdk.api.configuration.ClientCredentials;
import dev.openfga.sdk.api.configuration.Credentials;

// FGA_API_URL = 'https://api.us1.fga.dev' for Dev Preview and Early Access / 'https://api.playground.fga.dev' for the FGA Playground
// 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 = 'fga.us.auth0.com' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// 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 / not needed for the FGA Playground
// 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 / not needed for the FGA Playground

public class Example {
  public static void main(String[] args) throws Exception {
      var config = new ClientConfiguration()
              .apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "https://localhost:8080"
              .storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores()
              .authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request
              .credentials(new Credentials(
                  new ClientCredentials()
                          .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
                          .apiAudience(System.getenv("FGA_API_AUDIENCE"))
                          .clientId(System.getenv("FGA_CLIENT_ID"))
                          .clientSecret(System.getenv("FGA_CLIENT_SECRET"))
              ));

      var fgaClient = new OpenFgaClient(config);
  }
}

CLI

Set the required environment variables
# For all environments
export 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
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_SERVER_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'fga.us.auth0.com'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export 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
export 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

curl

To obtain the access token:

# Not needed when calling the Playground API
curl -X POST \
   https://fga.us.auth0.com/oauth/token \
   -H 'content-type: application/json' \
   -d '{"client_id":"'$FGA_CLIENT_ID'","client_secret":"'$FGA_CLIENT_SECRET'","audience":"https://api.us1.fga.dev/","grant_type":"client_credentials"}'

# The response will be returned in the form
# {
#  "access_token": "eyJ...Ggg",
#  "expires_in": 86400,
#  "scope": "read:tuples write:tuples check:tuples ... write:authorization-models",
#  "token_type": "Bearer"
# }
# Store this `access_token` value in environment variable `FGA_BEARER_TOKEN`

FGA_SERVER_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU

02. Calling Write API To Add New Relationship Tuples

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

Node.js

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

Go

options := ClientWriteOptions{
    AuthorizationModelId: PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
}

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             User: "user:anne",
             Relation: "reader",
             Object: "document:Z",
        }, 
    }, 
}

data, err := fgaClient.Write(context.Background()).
    Body(body).
    Options(options).
    Execute()

if err != nil {
    // .. Handle error
}

_ = data // use the response

.NET

var options = new ClientWriteOptions {
    AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
       new() {
                  User = "user:anne",
                  Relation = "reader",
                  Object = "document:Z"
              }
  },
};
var response = await fgaClient.Write(body, options);

Python

options = {
    "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    user="user:anne",
                    relation="reader",
                    object="document:Z",
                ),
        ],
)

response = await fga_client.write(body, options)

Java

var options = new ClientWriteOptions()
        .authorizationModelId("1uHxCSuTP0VKPYSnkq1pbb1jeZw");

var body = new ClientWriteRequest()
        .writes(List.of(
                new ClientTupleKey()
                        .user("user:anne")
                        .relation("reader")
                        ._object("document:Z")
        ));

var response = fgaClient.write(body, options).get();

CLI

fga tuple write --store-id=${FGA_STORE_ID} --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw user:anne reader document:Z 

curl

curl -X POST $FGA_SERVER_URL/stores/$FGA_STORE_ID/write \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"writes": { "tuple_keys" : [{"user":"user:anne","relation":"reader","object":"document:Z"}] }, "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

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',
}

Node.js

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

Go

options := ClientWriteOptions{
    AuthorizationModelId: PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
}

body := ClientWriteRequest{
    Deletes: []ClientTupleKeyWithoutCondition{
        {
             User: "user:anne",
             Relation: "reader",
             Object: "document:Z",
        }, 
    }, 
}

data, err := fgaClient.Write(context.Background()).
    Body(body).
    Options(options).
    Execute()

if err != nil {
    // .. Handle error
}

_ = data // use the response

.NET

var options = new ClientWriteOptions {
    AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
};
var body = new ClientWriteRequest() {
    Deletes = new List<ClientTupleKeyWithoutCondition>() {
    new() { User = "user:anne", Relation = "reader", Object = "document:Z" }
  },
};
var response = await fgaClient.Write(body, options);

Python

options = {
    "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
}
body = ClientWriteRequest(
        deletes=[
                ClientTuple(
                    user="user:anne",
                    relation="reader",
                    object="document:Z",
                ),
        ],
)

response = await fga_client.write(body, options)

Java

var options = new ClientWriteOptions()
        .authorizationModelId("1uHxCSuTP0VKPYSnkq1pbb1jeZw");

var body = new ClientWriteRequest() 
        .deletes(List.of(
                new ClientTupleKey()
                        .user("user:anne")
                        .relation("reader")
                        ._object("document:Z")
        ));

var response = fgaClient.write(body, options).get();

CLI

fga tuple delete --store-id=${FGA_STORE_ID} user:anne reader document:Z

curl

curl -X POST $FGA_SERVER_URL/stores/$FGA_STORE_ID/write \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"deletes": { "tuple_keys" : [{"user":"user:anne","relation":"reader","object":"document:Z"}] }, "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

Related Sections

Check the following sections for more on how to write your authorization data

Managing User Access

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

• More

Managing Group Access

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

• More

Transactional Writes

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

• More