Modeling Google Drive permissions with OpenFGA

This tutorial explains how to represent Google Drive permissions model with OpenFGA.

What you will learn

• Indicate relationships between a group of users and an object. See Modeling User Groups for more.
  Used here to indicate that all users within a domain can access a document (sharing a document within an organization).
• Model concentric relationship to have a certain relation on an object imply another relation on the same object. See Modeling Concepts: Concentric Relationships for more.
  Used here is to indicate that writers are also commenters and viewers.
• Using the union operator condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated.
  Used here to indicate that a user can be a viewer on a document, or can have the viewer relationship implied through commenter.
• Using the type bound public access in a relationship tuple's user field to indicate that everyone has a certain relation with an object. See Modeling Public Access for more.
  Used here to share documents publicly.
• Model parent-child objects to indicate that a user having a relationship with a certain object implies having a relationship with another object in OpenFGA.
  Used here is to indicate that a writer on a folder is a writer on all documents inside that folder.

Before you start

In order to understand this guide correctly you must be familiar with some OpenFGA concepts and know how to develop the things that we will list below.

OpenFGA concepts

It would be helpful to have an understanding of some concepts of OpenFGA before you start.

Modeling concentric relationships

You need to know how to update the authorization model to allow having nested relations such as all writers are readers. Learn more →

Modeling object-to-object relationships

You need to know how to create relationships between objects and how that might affect a user's relationships to those objects. Learn more →

Used here to indicate that users who have access to view a folder have access to view all documents inside it.

Modeling public access

You need to know how to add a relationship tuple to indicate that a resource is publicly available. Learn more →

Concepts & configuration language

• The OpenFGA Concepts
• Configuration Language

What you will be modeling

Google Drive is a system to store, share, and collaborate on files and folders. Source

In this tutorial, you will build a subset of the Google Drive permission model (detailed below) in OpenFGA, using some scenarios to validate the model.

Note: For brevity, this tutorial will not model all of Google Drive's permissions. Instead, it will focus on modeling for the scenarios outlined below

Requirements

Google Drive's permission model is represented in their documentation.

In this tutorial, you will be focusing on a subset of these permissions.

Requirements:

• Users can be owners, editors, commenters and viewers of documents
• Documents can be shared with all users in a domain
• Folders can contain documents and users with a certain permission on a folder have that same permission to a document in that folder
• Documents and folders can be shared publicly

Defined scenarios

There will be the following users:

• Anne, who is in the xyz domain
• Beth, who is in the xyz domain
• Charles, who is in the xyz domain
• Diane, who is NOT in the xyz domain
• Erik, who is NOT in the xyz domain

There will be:

• a 2021-budget document, owned by Anne, shared for commenting with Beth and viewable by all members of the xyz domain.
• a 2021-planning folder, viewable by Diane and contains the 2021-budget document
• a 2021-public-roadmap document, owned by Anne, available for members xyz domain to comment on and is publicly viewable

Modeling Google Drive's permissions

01. Individual permissions

To keep thing simple and focus on OpenFGA features rather than Google Drive complexity we will model only four roles (Viewer, Commenter, Writer, Owner).

At the end of this section we want to have the following permissions represented:

To represent permissions in OpenFGA we use relations. For document permissions we need to create the following authorization model:

DSL

model
  schema 1.1

type user

type document
  relations
    define owner: [user]
    define writer: [user]
    define commenter: [user]
    define viewer: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "owner": {
          "this": {}
        },
        "writer": {
          "this": {}
        },
        "commenter": {
          "this": {}
        },
        "viewer": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "commenter": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

The OpenFGA service determines if a user has access to an object by checking if the user has a relation to that object. Let us examine one of those relations in detail:

DSL

type document
  relations
    define viewer: [user]

JSON

{
  "type": "document",
  "relations": {
    "viewer": {
      "this": {}
    }
  },
  "metadata": {
    "relations": {
      "viewer": {
        "directly_related_user_types": [
          {
            "type": "user"
          }
        ]
      }
    }
  }
}

info

The snippet above indicates that objects of type document have users related to them as "viewer" if those users belong to the userset of all users related to the document as "viewer".

This means that a user can be directly related as a viewer to an object of type "document"

If we want to say beth is a commenter of document:2021-budget we create this relationship tuple:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

await fgaClient.write({
  writes: [
      {"user":"user:beth","relation":"commenter","object":"document:2021-budget"}
  ],
}, {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientWriteOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             User: "user:beth",
             Relation: "commenter",
             Object: "document:2021-budget",
        }, 
    }, 
}

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

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

_ = data // use the response

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
       new() {
                  User = "user:beth",
                  Relation = "commenter",
                  Object = "document:2021-budget"
              }
  },
};
var response = await fgaClient.Write(body, options);

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    user="user:beth",
                    relation="commenter",
                    object="document:2021-budget",
                ),
        ],
)

response = await fga_client.write(body, options)

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientWriteOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientWriteRequest()
        .writes(List.of(
                new ClientTupleKey()
                        .user("user:beth")
                        .relation("commenter")
                        ._object("document:2021-budget")
        ));

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

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_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:beth","relation":"commenter","object":"document:2021-budget"}] }, "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"}'

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:beth commenter document:2021-budget 

Pseudocode

write([
    {
      "user":"user:beth",
      "relation":"commenter",
      "object":"document:2021-budget"
    }
], authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA")

We can now ask OpenFGA "is beth a commenter of repository document:2021-budget?"

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:beth',
    relation: 'commenter',
    object: 'document:2021-budget',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:beth",
    Relation: "commenter",
    Object:   "document:2021-budget",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:beth",
    Relation = "commenter",
    Object = "document:2021-budget",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:beth",
    relation="commenter",
    object="document:2021-budget",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:beth")
        .relation("commenter")
        ._object("document:2021-budget");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:beth commenter document:2021-budget

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:beth","relation":"commenter","object":"document:2021-budget"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:beth", // check if the user `user:beth`
  relation = "commenter", // has an `commenter` relation
  object = "document:2021-budget", // with the object `document:2021-budget`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:beth related to document:2021-budget as commenter?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

We could also say that anne is an owner of the same document:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

await fgaClient.write({
  writes: [
      {"user":"user:anne","relation":"owner","object":"document:2021-budget"}
  ],
}, {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientWriteOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             User: "user:anne",
             Relation: "owner",
             Object: "document:2021-budget",
        }, 
    }, 
}

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

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

_ = data // use the response

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
       new() {
                  User = "user:anne",
                  Relation = "owner",
                  Object = "document:2021-budget"
              }
  },
};
var response = await fgaClient.Write(body, options);

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    user="user:anne",
                    relation="owner",
                    object="document:2021-budget",
                ),
        ],
)

response = await fga_client.write(body, options)

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientWriteOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientWriteRequest()
        .writes(List.of(
                new ClientTupleKey()
                        .user("user:anne")
                        .relation("owner")
                        ._object("document:2021-budget")
        ));

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

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_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":"owner","object":"document:2021-budget"}] }, "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"}'

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne owner document:2021-budget 

Pseudocode

write([
    {
      "user":"user:anne",
      "relation":"owner",
      "object":"document:2021-budget"
    }
], authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA")

And ask some questions to OpenFGA:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'owner',
    object: 'document:2021-budget',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:anne",
    Relation: "owner",
    Object:   "document:2021-budget",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "owner",
    Object = "document:2021-budget",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:anne",
    relation="owner",
    object="document:2021-budget",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:anne")
        .relation("owner")
        ._object("document:2021-budget");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne owner document:2021-budget

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:anne","relation":"owner","object":"document:2021-budget"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "owner", // has an `owner` relation
  object = "document:2021-budget", // with the object `document:2021-budget`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:anne related to document:2021-budget as owner?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'writer',
    object: 'document:2021-budget',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = false

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:anne",
    Relation: "writer",
    Object:   "document:2021-budget",
}

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

// data = { allowed: false }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "writer",
    Object = "document:2021-budget",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = false

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:anne",
    relation="writer",
    object="document:2021-budget",
)

response = await fga_client.check(body, options)

# response.allowed = false

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:anne")
        .relation("writer")
        ._object("document:2021-budget");

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

// response.getAllowed() = false 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne writer document:2021-budget

# Response: {"allowed":false}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:anne","relation":"writer","object":"document:2021-budget"}}'

# Response: {"allowed":false}

Pseudocode

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "writer", // has an `writer` relation
  object = "document:2021-budget", // with the object `document:2021-budget`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: false

Playground

is user:anne related to document:2021-budget as writer?


# Response: A red object indicating that the response from the API is `{"allowed":false}`

The first reply makes sense but the second one does not. Intuitively, if anne was an owner, she was also be a writer. In fact, Google Drive explains this in their documentation

To make OpenFGA aware of this "concentric" permission model we need to update our definitions:

DSL

model
  schema 1.1

type user

type document
  relations
    define owner: [user]
    define writer: [user] or owner
    define commenter: [user] or writer
    define viewer: [user] or commenter

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "owner": {
          "this": {}
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "owner"
                }
              }
            ]
          }
        },
        "commenter": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              }
            ]
          }
        },
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "commenter"
                }
              }
            ]
          }
        }
      },
      "metadata": {
        "relations": {
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "commenter": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

info

Let's examine one of those relations in detail:

objects of type document have users related to them as "viewer": if they belong to any of (the union of) the following:

• the userset of all users related to the document as "viewer"
• the userset of all users related to the document as "commenter"

With this update our model now supports nested definitions and now:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'owner',
    object: 'document:2021-budget',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:anne",
    Relation: "owner",
    Object:   "document:2021-budget",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "owner",
    Object = "document:2021-budget",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:anne",
    relation="owner",
    object="document:2021-budget",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:anne")
        .relation("owner")
        ._object("document:2021-budget");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne owner document:2021-budget

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:anne","relation":"owner","object":"document:2021-budget"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "owner", // has an `owner` relation
  object = "document:2021-budget", // with the object `document:2021-budget`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:anne related to document:2021-budget as owner?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'writer',
    object: 'document:2021-budget',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:anne",
    Relation: "writer",
    Object:   "document:2021-budget",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "writer",
    Object = "document:2021-budget",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:anne",
    relation="writer",
    object="document:2021-budget",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:anne")
        .relation("writer")
        ._object("document:2021-budget");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne writer document:2021-budget

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:anne","relation":"writer","object":"document:2021-budget"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "writer", // has an `writer` relation
  object = "document:2021-budget", // with the object `document:2021-budget`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:anne related to document:2021-budget as writer?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

02. Organization permissions

Google Drive allows you to share a file with everyone in your organization as a viewer, commenter or writer/editor.

At the end of this section we want to end up with the following permissions represented:

To add support for domains and members all we need to do is add this object to the OpenFGA authorization model. In addition, update the model to allow domain member to be assigned to document:

DSL

model
  schema 1.1

type user

type document
  relations
    define owner: [user, domain#member]
    define writer: [user, domain#member] or owner
    define commenter: [user, domain#member] or writer
    define viewer: [user, domain#member] or commenter

type domain
  relations
    define member: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "owner": {
          "this": {}
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "owner"
                }
              }
            ]
          }
        },
        "commenter": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              }
            ]
          }
        },
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "commenter"
                }
              }
            ]
          }
        }
      },
      "metadata": {
        "relations": {
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "commenter": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          }
        }
      }
    },
    {
      "type": "domain",
      "relations": {
        "member": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "member": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

info

Objects of type "domain" have users related to them as "member" if they belong to the userset of all users related to the domain as "member".

In other words, users can be direct members of a domain.

Let's now create a domain, add members to it and make all members viewers of document:2021-budget.

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

await fgaClient.write({
  writes: [
      // make anne, beth, charles a member of the xyz domain
      {"_description":"make anne, beth, charles a member of the xyz domain","user":"user:anne","relation":"member","object":"domain:xyz"},
      {"user":"user:beth","relation":"member","object":"domain:xyz"},
      {"user":"user:charles","relation":"member","object":"domain:xyz"},
      // make members of xyz domain viewers of document:2021-budget
      {"_description":"make members of xyz domain viewers of document:2021-budget","user":"domain:xyz#member","relation":"viewer","object":"document:2021-budget"}
  ],
}, {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientWriteOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             // make anne, beth, charles a member of the xyz domain
             User: "user:anne",
             Relation: "member",
             Object: "domain:xyz",
        },         {
             User: "user:beth",
             Relation: "member",
             Object: "domain:xyz",
        },         {
             User: "user:charles",
             Relation: "member",
             Object: "domain:xyz",
        },         {
             // make members of xyz domain viewers of document:2021-budget
             User: "domain:xyz#member",
             Relation: "viewer",
             Object: "document:2021-budget",
        }, 
    }, 
}

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

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

_ = data // use the response

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
    // make anne, beth, charles a member of the xyz domain
       new() {
                  User = "user:anne",
                  Relation = "member",
                  Object = "domain:xyz"
              },
       new() {
                  User = "user:beth",
                  Relation = "member",
                  Object = "domain:xyz"
              },
       new() {
                  User = "user:charles",
                  Relation = "member",
                  Object = "domain:xyz"
              },
    // make members of xyz domain viewers of document:2021-budget
       new() {
                  User = "domain:xyz#member",
                  Relation = "viewer",
                  Object = "document:2021-budget"
              }
  },
};
var response = await fgaClient.Write(body, options);

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    # make anne, beth, charles a member of the xyz domain
                    user="user:anne",
                    relation="member",
                    object="domain:xyz",
                ),
                ClientTuple(
                    user="user:beth",
                    relation="member",
                    object="domain:xyz",
                ),
                ClientTuple(
                    user="user:charles",
                    relation="member",
                    object="domain:xyz",
                ),
                ClientTuple(
                    # make members of xyz domain viewers of document:2021-budget
                    user="domain:xyz#member",
                    relation="viewer",
                    object="document:2021-budget",
                ),
        ],
)

response = await fga_client.write(body, options)

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientWriteOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientWriteRequest()
        .writes(List.of(
                // make anne, beth, charles a member of the xyz domain
                new ClientTupleKey()
                        .user("user:anne")
                        .relation("member")
                        ._object("domain:xyz"),
                new ClientTupleKey()
                        .user("user:beth")
                        .relation("member")
                        ._object("domain:xyz"),
                new ClientTupleKey()
                        .user("user:charles")
                        .relation("member")
                        ._object("domain:xyz"),
                // make members of xyz domain viewers of document:2021-budget
                new ClientTupleKey()
                        .user("domain:xyz#member")
                        .relation("viewer")
                        ._object("document:2021-budget")
        ));

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

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_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" : [{"_description":"make anne, beth, charles a member of the xyz domain","user":"user:anne","relation":"member","object":"domain:xyz"},{"user":"user:beth","relation":"member","object":"domain:xyz"},{"user":"user:charles","relation":"member","object":"domain:xyz"},{"_description":"make members of xyz domain viewers of document:2021-budget","user":"domain:xyz#member","relation":"viewer","object":"document:2021-budget"}] }, "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"}'

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne member domain:xyz 
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:beth member domain:xyz 
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:charles member domain:xyz 
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA domain:xyz#member viewer document:2021-budget 

Pseudocode

write([
    // make anne, beth, charles a member of the xyz domain
    {
      "user":"user:anne",
      "relation":"member",
      "object":"domain:xyz"
    },
    {
      "user":"user:beth",
      "relation":"member",
      "object":"domain:xyz"
    },
    {
      "user":"user:charles",
      "relation":"member",
      "object":"domain:xyz"
    },
    // make members of xyz domain viewers of document:2021-budget
    {
      "user":"domain:xyz#member",
      "relation":"viewer",
      "object":"document:2021-budget"
    }
], authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA")

The last relationship tuple introduces a new OpenFGA concept. A userset. When the value of a user is formatted like this objectType:objectId#relation, OpenFGA will automatically expand the userset into all its individual user identifiers:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:charles',
    relation: 'viewer',
    object: 'document:2021-budget',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:charles",
    Relation: "viewer",
    Object:   "document:2021-budget",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:charles",
    Relation = "viewer",
    Object = "document:2021-budget",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:charles",
    relation="viewer",
    object="document:2021-budget",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:charles")
        .relation("viewer")
        ._object("document:2021-budget");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:charles viewer document:2021-budget

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:charles","relation":"viewer","object":"document:2021-budget"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:charles", // check if the user `user:charles`
  relation = "viewer", // has an `viewer` relation
  object = "document:2021-budget", // with the object `document:2021-budget`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:charles related to document:2021-budget as viewer?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

03. Folder permission propagation

Permission propagation happens between folders and files: if you are a viewer in a folder, you can view its documents. This applies even when you are not explicitly a viewer in a document.

At the end of this section we want to end up with the following permissions represented. Note that a folder is an object in the document type, as we do not need a separate type:

We need to add the notion that a document can be the parent of another document. We know how to do that:

DSL

model
  schema 1.1

type user

type document
  relations
    define parent: [document]
    define owner: [user, domain#member]
    define writer: [user, domain#member] or owner
    define commenter: [user, domain#member] or writer
    define viewer: [user, domain#member] or commenter

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "parent": {
          "this": {}
        },
        "owner": {
          "this": {}
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "owner"
                }
              }
            ]
          }
        },
        "commenter": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              }
            ]
          }
        },
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "commenter"
                }
              }
            ]
          }
        }
      },
      "metadata": {
        "relations": {
          "parent": {
            "directly_related_user_types": [
              {
                "type": "document"
              }
            ]
          },
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "commenter": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          }
        }
      }
    }
  ]
}

info

Notice the newly added "parent" relation in the configuration above.

We can indicate this relation by adding the following relationship tuples

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

await fgaClient.write({
  writes: [
      // Diane is a viewer of document:2021-planning
      {"_description":"Diane is a viewer of document:2021-planning","user":"user:diane","relation":"viewer","object":"document:2021-planning"},
      // document:2021-planning is a parent of document:2021-budget
      {"_description":"document:2021-planning is a parent of document:2021-budget","user":"document:2021-planning","relation":"parent","object":"document:2021-budget"}
  ],
}, {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientWriteOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             // Diane is a viewer of document:2021-planning
             User: "user:diane",
             Relation: "viewer",
             Object: "document:2021-planning",
        },         {
             // document:2021-planning is a parent of document:2021-budget
             User: "document:2021-planning",
             Relation: "parent",
             Object: "document:2021-budget",
        }, 
    }, 
}

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

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

_ = data // use the response

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
    // Diane is a viewer of document:2021-planning
       new() {
                  User = "user:diane",
                  Relation = "viewer",
                  Object = "document:2021-planning"
              },
    // document:2021-planning is a parent of document:2021-budget
       new() {
                  User = "document:2021-planning",
                  Relation = "parent",
                  Object = "document:2021-budget"
              }
  },
};
var response = await fgaClient.Write(body, options);

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    # Diane is a viewer of document:2021-planning
                    user="user:diane",
                    relation="viewer",
                    object="document:2021-planning",
                ),
                ClientTuple(
                    # document:2021-planning is a parent of document:2021-budget
                    user="document:2021-planning",
                    relation="parent",
                    object="document:2021-budget",
                ),
        ],
)

response = await fga_client.write(body, options)

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientWriteOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientWriteRequest()
        .writes(List.of(
                // Diane is a viewer of document:2021-planning
                new ClientTupleKey()
                        .user("user:diane")
                        .relation("viewer")
                        ._object("document:2021-planning"),
                // document:2021-planning is a parent of document:2021-budget
                new ClientTupleKey()
                        .user("document:2021-planning")
                        .relation("parent")
                        ._object("document:2021-budget")
        ));

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

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_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" : [{"_description":"Diane is a viewer of document:2021-planning","user":"user:diane","relation":"viewer","object":"document:2021-planning"},{"_description":"document:2021-planning is a parent of document:2021-budget","user":"document:2021-planning","relation":"parent","object":"document:2021-budget"}] }, "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"}'

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:diane viewer document:2021-planning 
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA document:2021-planning parent document:2021-budget 

Pseudocode

write([
    // Diane is a viewer of document:2021-planning
    {
      "user":"user:diane",
      "relation":"viewer",
      "object":"document:2021-planning"
    },
    // document:2021-planning is a parent of document:2021-budget
    {
      "user":"document:2021-planning",
      "relation":"parent",
      "object":"document:2021-budget"
    }
], authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA")

What we still lack is the ability to propagate permissions from parent to children. We want to say that a user is a viewer of a document if either:

• [done] they have a viewer relationship (directly or through domain membership)
• [pending] they have a viewer relationship with the parent document

We need a way to consider the parent viewers, not just direct viewers of the document when getting a check for:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:diane',
    relation: 'viewer',
    object: 'document:2021-budget',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = undefined

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:diane",
    Relation: "viewer",
    Object:   "document:2021-budget",
}

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

// data = { allowed: undefined }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:diane",
    Relation = "viewer",
    Object = "document:2021-budget",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = undefined

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:diane",
    relation="viewer",
    object="document:2021-budget",
)

response = await fga_client.check(body, options)

# response.allowed = undefined

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:diane")
        .relation("viewer")
        ._object("document:2021-budget");

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

// response.getAllowed() = undefined 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:diane viewer document:2021-budget

# Response: {"allowed":undefined}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:diane","relation":"viewer","object":"document:2021-budget"}}'

# Response: {"allowed":undefined}

Pseudocode

check(
  user = "user:diane", // check if the user `user:diane`
  relation = "viewer", // has an `viewer` relation
  object = "document:2021-budget", // with the object `document:2021-budget`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: undefined

Playground

is user:diane related to document:2021-budget as viewer?


# Response: A red object indicating that the response from the API is `{"allowed":false}`

More details on this technique can be found in the section Modeling Parent-Child Objects.

We express it like this:

DSL

type document
  relations
    define viewer: [user, domain#member] or commenter or viewer from parent

JSON

{
  "type": "document",
  "relations": {
    "viewer": {
      "union": {
        "child": [
          {
            "this": {}
          },
          {
            "computedUserset": {
              "relation": "commenter"
            }
          },
          {
            "tupleToUserset": {
              "tupleset": {
                "relation": "parent"
              },
              "computedUserset": {
                "relation": "viewer"
              }
            }
          }
        ]
      }
    }
  },
  "metadata": {
    "relations": {
      "viewer": {
        "directly_related_user_types": [
          {
            "type": "user"
          },
          {
            "type": "domain",
            "relation": "member"
          }
        ]
      }
    }
  }
}

info

The users with a viewer relationship to a certain object of type "document" are any of:

• the "viewers": the set of users who are directly related to the document as a "viewer"
• the "commenters": the set of users who are related to the object as "commenter"
• the "viewers of the parents": from the objects who are related to the doc as parent, return the sets of users who are related to those objects as "viewer"

What the added section is doing is:

1. read all relationship tuples related to document:2021-budget as parent which returns:

[{ "object": "document:2021-budget", "relation": "parent", "user": "document:2021-planning" }]

2. for each relationship tuple read, return all usersets that match the following, returning tuples of shape:

{ "object": "document:2021-planning", "viewer", "user": ??? }

including: { "object": "document:2021-planning", "viewer", "user": "user:diane" }

The updated authorization model looks like this:

DSL

model
  schema 1.1

type user

type document
  relations
    define owner: [user, domain#member] or owner from parent
    define writer: [user, domain#member] or owner or writer from parent
    define commenter: [user, domain#member] or writer or commenter from parent
    define viewer: [user, domain#member] or commenter or viewer from parent
    define parent: [document]

type domain
  relations
    define member: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "owner": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "owner"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "owner"
                }
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "writer"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "commenter": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "commenter"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "commenter"
                }
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "viewer"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "parent": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "parent": {
            "directly_related_user_types": [
              {
                "type": "document"
              }
            ]
          },
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "commenter": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          }
        }
      }
    },
    {
      "type": "domain",
      "relations": {
        "member": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "member": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

04. Sharing files and folders publicly

Google Drive has a feature which allows sharing a file or folder publicly, and specifying the permissions a public user might have (writer/commenter/viewer).

Assume that Anne has created a new document: 2021-public-roadmap, has shared it with commenter permissions to the xyz.com, and has shared it as view only with the public at large.

Here's where another OpenFGA feature, type bound public access (as in everyone), would come in handy.

First, we will need to update our model to allow for public access with type user for viewer relation.

DSL

model
  schema 1.1

type user

type document
  relations
    define owner: [user, domain#member] or owner from parent
    define writer: [user, domain#member] or owner or writer from parent
    define commenter: [user, domain#member] or writer or commenter from parent
    define viewer: [user, user:*, domain#member] or commenter or viewer from parent
    define parent: [document]

type domain
  relations
    define member: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "owner": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "owner"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "owner"
                }
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "writer"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "commenter": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "commenter"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "commenter"
                }
              },
              {
                "tupleToUserset": {
                  "computedUserset": {
                    "relation": "viewer"
                  },
                  "tupleset": {
                    "relation": "parent"
                  }
                }
              }
            ]
          }
        },
        "parent": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "parent": {
            "directly_related_user_types": [
              {
                "type": "document"
              }
            ]
          },
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "commenter": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "user",
                "wildcard": {}
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          }
        }
      }
    },
    {
      "type": "domain",
      "relations": {
        "member": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "member": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

To mark Anne as the owner, the domain members as commenters and the public as viewers, we need to add the following relationship tuples:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

await fgaClient.write({
  writes: [
      // Anne is the owner of document:2021-public-roadmap
      {"_description":"Anne is the owner of document:2021-public-roadmap","user":"user:anne","relation":"owner","object":"document:2021-public-roadmap"},
      // Members of the domain:xyz can comment on document:2021-public-roadmap
      {"_description":"Members of the domain:xyz can comment on document:2021-public-roadmap","user":"domain:xyz#member","relation":"commenter","object":"document:2021-public-roadmap"},
      // Everyone with type `user` can view document:2021-public-roadmap
      {"_description":"Everyone with type `user` can view document:2021-public-roadmap","user":"user:*","relation":"viewer","object":"document:2021-public-roadmap"}
  ],
}, {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientWriteOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             // Anne is the owner of document:2021-public-roadmap
             User: "user:anne",
             Relation: "owner",
             Object: "document:2021-public-roadmap",
        },         {
             // Members of the domain:xyz can comment on document:2021-public-roadmap
             User: "domain:xyz#member",
             Relation: "commenter",
             Object: "document:2021-public-roadmap",
        },         {
             // Everyone with type `user` can view document:2021-public-roadmap
             User: "user:*",
             Relation: "viewer",
             Object: "document:2021-public-roadmap",
        }, 
    }, 
}

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

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

_ = data // use the response

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
    // Anne is the owner of document:2021-public-roadmap
       new() {
                  User = "user:anne",
                  Relation = "owner",
                  Object = "document:2021-public-roadmap"
              },
    // Members of the domain:xyz can comment on document:2021-public-roadmap
       new() {
                  User = "domain:xyz#member",
                  Relation = "commenter",
                  Object = "document:2021-public-roadmap"
              },
    // Everyone with type `user` can view document:2021-public-roadmap
       new() {
                  User = "user:*",
                  Relation = "viewer",
                  Object = "document:2021-public-roadmap"
              }
  },
};
var response = await fgaClient.Write(body, options);

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    # Anne is the owner of document:2021-public-roadmap
                    user="user:anne",
                    relation="owner",
                    object="document:2021-public-roadmap",
                ),
                ClientTuple(
                    # Members of the domain:xyz can comment on document:2021-public-roadmap
                    user="domain:xyz#member",
                    relation="commenter",
                    object="document:2021-public-roadmap",
                ),
                ClientTuple(
                    # Everyone with type `user` can view document:2021-public-roadmap
                    user="user:*",
                    relation="viewer",
                    object="document:2021-public-roadmap",
                ),
        ],
)

response = await fga_client.write(body, options)

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientWriteOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientWriteRequest()
        .writes(List.of(
                // Anne is the owner of document:2021-public-roadmap
                new ClientTupleKey()
                        .user("user:anne")
                        .relation("owner")
                        ._object("document:2021-public-roadmap"),
                // Members of the domain:xyz can comment on document:2021-public-roadmap
                new ClientTupleKey()
                        .user("domain:xyz#member")
                        .relation("commenter")
                        ._object("document:2021-public-roadmap"),
                // Everyone with type `user` can view document:2021-public-roadmap
                new ClientTupleKey()
                        .user("user:*")
                        .relation("viewer")
                        ._object("document:2021-public-roadmap")
        ));

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

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_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" : [{"_description":"Anne is the owner of document:2021-public-roadmap","user":"user:anne","relation":"owner","object":"document:2021-public-roadmap"},{"_description":"Members of the domain:xyz can comment on document:2021-public-roadmap","user":"domain:xyz#member","relation":"commenter","object":"document:2021-public-roadmap"},{"_description":"Everyone with type `user` can view document:2021-public-roadmap","user":"user:*","relation":"viewer","object":"document:2021-public-roadmap"}] }, "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"}'

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne owner document:2021-public-roadmap 
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA domain:xyz#member commenter document:2021-public-roadmap 
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:* viewer document:2021-public-roadmap 

Pseudocode

write([
    // Anne is the owner of document:2021-public-roadmap
    {
      "user":"user:anne",
      "relation":"owner",
      "object":"document:2021-public-roadmap"
    },
    // Members of the domain:xyz can comment on document:2021-public-roadmap
    {
      "user":"domain:xyz#member",
      "relation":"commenter",
      "object":"document:2021-public-roadmap"
    },
    // Everyone with type `user` can view document:2021-public-roadmap
    {
      "user":"user:*",
      "relation":"viewer",
      "object":"document:2021-public-roadmap"
    }
], authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA")

Anne is an owner of the document

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'owner',
    object: 'document:2021-public-roadmap',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:anne",
    Relation: "owner",
    Object:   "document:2021-public-roadmap",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "owner",
    Object = "document:2021-public-roadmap",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:anne",
    relation="owner",
    object="document:2021-public-roadmap",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:anne")
        .relation("owner")
        ._object("document:2021-public-roadmap");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne owner document:2021-public-roadmap

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:anne","relation":"owner","object":"document:2021-public-roadmap"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "owner", // has an `owner` relation
  object = "document:2021-public-roadmap", // with the object `document:2021-public-roadmap`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:anne related to document:2021-public-roadmap as owner?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

Beth is a member of the xyz.com domain, and so can comment but cannot write

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:beth',
    relation: 'writer',
    object: 'document:2021-public-roadmap',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = false

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:beth",
    Relation: "writer",
    Object:   "document:2021-public-roadmap",
}

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

// data = { allowed: false }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:beth",
    Relation = "writer",
    Object = "document:2021-public-roadmap",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = false

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:beth",
    relation="writer",
    object="document:2021-public-roadmap",
)

response = await fga_client.check(body, options)

# response.allowed = false

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:beth")
        .relation("writer")
        ._object("document:2021-public-roadmap");

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

// response.getAllowed() = false 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:beth writer document:2021-public-roadmap

# Response: {"allowed":false}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:beth","relation":"writer","object":"document:2021-public-roadmap"}}'

# Response: {"allowed":false}

Pseudocode

check(
  user = "user:beth", // check if the user `user:beth`
  relation = "writer", // has an `writer` relation
  object = "document:2021-public-roadmap", // with the object `document:2021-public-roadmap`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: false

Playground

is user:beth related to document:2021-public-roadmap as writer?


# Response: A red object indicating that the response from the API is `{"allowed":false}`

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:beth',
    relation: 'commenter',
    object: 'document:2021-public-roadmap',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:beth",
    Relation: "commenter",
    Object:   "document:2021-public-roadmap",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:beth",
    Relation = "commenter",
    Object = "document:2021-public-roadmap",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:beth",
    relation="commenter",
    object="document:2021-public-roadmap",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:beth")
        .relation("commenter")
        ._object("document:2021-public-roadmap");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:beth commenter document:2021-public-roadmap

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:beth","relation":"commenter","object":"document:2021-public-roadmap"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:beth", // check if the user `user:beth`
  relation = "commenter", // has an `commenter` relation
  object = "document:2021-public-roadmap", // with the object `document:2021-public-roadmap`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:beth related to document:2021-public-roadmap as commenter?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

Erik is NOT a member of the xyz.com domain, and so can only view the document

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:erik',
    relation: 'writer',
    object: 'document:2021-public-roadmap',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = false

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:erik",
    Relation: "writer",
    Object:   "document:2021-public-roadmap",
}

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

// data = { allowed: false }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:erik",
    Relation = "writer",
    Object = "document:2021-public-roadmap",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = false

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:erik",
    relation="writer",
    object="document:2021-public-roadmap",
)

response = await fga_client.check(body, options)

# response.allowed = false

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:erik")
        .relation("writer")
        ._object("document:2021-public-roadmap");

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

// response.getAllowed() = false 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:erik writer document:2021-public-roadmap

# Response: {"allowed":false}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:erik","relation":"writer","object":"document:2021-public-roadmap"}}'

# Response: {"allowed":false}

Pseudocode

check(
  user = "user:erik", // check if the user `user:erik`
  relation = "writer", // has an `writer` relation
  object = "document:2021-public-roadmap", // with the object `document:2021-public-roadmap`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: false

Playground

is user:erik related to document:2021-public-roadmap as writer?


# Response: A red object indicating that the response from the API is `{"allowed":false}`

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// 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
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:erik',
    relation: 'viewer',
    object: 'document:2021-public-roadmap',
  }, {
  authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. https://api.fga.example
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:erik",
    Relation: "viewer",
    Object:   "document:2021-public-roadmap",
}

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

// data = { allowed: true }

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. https://api.fga.example
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientCheckRequest {
    User = "user:erik",
    Relation = "viewer",
    Object = "document:2021-public-roadmap",
    
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientCheckRequest(
    user="user:erik",
    relation="viewer",
    object="document:2021-public-roadmap",
)

response = await fga_client.check(body, options)

# response.allowed = true

Java

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:erik")
        .relation("viewer")
        ._object("document:2021-public-roadmap");

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

// response.getAllowed() = true 

CLI

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:erik viewer document:2021-public-roadmap

# Response: {"allowed":true}

curl

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_API_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/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", "tuple_key":{"user":"user:erik","relation":"viewer","object":"document:2021-public-roadmap"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:erik", // check if the user `user:erik`
  relation = "viewer", // has an `viewer` relation
  object = "document:2021-public-roadmap", // with the object `document:2021-public-roadmap`
   authorization_model_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

Playground

is user:erik related to document:2021-public-roadmap as viewer?


# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

Related Sections

Take a look at the following sections for more information.

Search with permissions

Give your users search results with objects that they have access to

• More