Roles and Permissions

In this guide you will learn how to model roles and permissions model within OpenFGA using the authorization model and relationship tuple.

• Roles are assigned to users or a group of users, where any user can have more than one role (editor, owner, etc..).
• Permissions are what allows users to access certain objects based on their specific roles (device_renamer, channel_archiver, etc..).

For example, the role viewer of a trip can have permissions to view bookings or the role owners can have permissions to add/view bookings to a trip.

When to use

When trying to create a role and permissions model within OpenFGA.:

• Create roles by creating relations that can be directly assigned to users
• Assign permissions by creating relations that users get through other relations

For example:

• Grant someone an admin role that can edit and read a document
• Grant someone a security_guard role that can live_video_viewer on a device
• Grant someone a viewer role that can view_products on a shop

There are advantages to implementing roles and permissions within OpenFGA, such as:

• Breaking down existing roles to have more fine grained permissions. This allows your application to check whether a user has access to a certain object without having to explicitly check that specific users role.
• Introduce new roles/permissions or consolidate roles without affecting your application behavior. For example: if in your app all the checks are for the fine permissions check('bob', 'booking_adder', 'trip:Europe') instead of check('bob', 'owner', 'trip:Europe'), and then you later decide owners can no longer add bookings to a trip, you can remove the relation within the trip type with no code changes in your application, and all the permissions will automatically honor the change.

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.

Assume that you have the following authorization model.
You have a type called trip that users can be related to as viewer and/or an owner.

DSL

model
  schema 1.1
type user
type trip
  relations
    define owner: [user]
    define viewer: [user]

JSON

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

---

In addition, you will need to know the following:

Direct Access

You need to know how to create an authorization model and create a relationship tuple to grant a user access to an object. Learn more →

OpenFGA Concepts

• A Type: a class of objects that have similar characteristics
• A User: an entity in the system that can be related to an object
• A Relation: is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system
• An Object: represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model
• A Relationship Tuple: a grouping consisting of a user, a relation and an object stored in Auth OpenFGA
• A Relationship: OpenFGA will be called to check if there is a relationship between a user and an object, indicating that the access is allowed
• Direct Relationship Type Restrictions: can be used to indicate direct relationships between users and objects
• A Check API Request the Check API Request is used to check for relationships between users and objects

Step By Step

To illustrate modeling Roles and Permissions in OpenFGA, we will use a trip booking system where you can have owners and/or viewers that can have more granular permissions such as adding bookings to a trip or viewing bookings on it.

In order to represent this, we need to:

1. Understand how roles are related to direct relations for our trip booking system
2. Adding implied relations to existing authorization model to define permissions for bookings
3. Checking user roles and their permissions based on *relationship tuples* for direct and implied relations

01. Understand How Roles Work Within Our Trip Booking System

Relating roles within OpenFGA can be best described as the following: Roles are relations that can be directly assigned to users. Looking at our authorization model, our roles would then be owner and viewer. Meaning that a specific user can be an owner and/or a viewer.

DSL

model
  schema 1.1
type user
type trip
  relations
    define owner: [user]
    define viewer: [user]

JSON

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

02. Adding Permissions For Bookings

Permissions within OpenFGA can be best described as the following: Permissions are relations that users get only through other relations. To represent permissions, we avoid adding a direct relationship type restriction to the relation in the authorization model. Instead, we define the relation from other relations to indicate that it is a permission granted to and implied from a different relation.

To add permissions related to bookings, we can add new relations to the trip object type denoting the various actions a user can take on trips (view, edit, delete, rename, etc...)

To allow viewers of a trip to have permissions to view bookings and owners to have permissions to add/view bookings, we would modify the type as the following:

DSL

model
  schema 1.1
type user
type trip
  relations
    define owner: [user]
    define viewer: [user]
    define booking_adder: owner
    define booking_viewer: viewer or owner

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "trip",
      "relations": {
        "owner": {
          "this": {}
        },
        "viewer": {
          "this": {}
        },
        "booking_adder": {
          "computedUserset": {
            "relation": "owner"
          }
        },
        "booking_viewer": {
          "union": {
            "child": [
              {
                "computedUserset": {
                  "relation": "viewer"
                }
              },
              {
                "computedUserset": {
                  "relation": "owner"
                }
              }
            ]
          }
        }
      },
      "metadata": {
        "relations": {
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

Note: notice how both booking_viewer and booking_adder don't have direct relationship type restrictions. This is to ensure that the relation can only be assigned through the role and not directly.

03. Checking User Roles And Their Permissions

Now that our type definitions reflects the roles and permissions on how bookings can be viewed/added. Let's create relationship tuples to assign roles to users and then check if users have the proper permissions.

Let us create two relationship tuples:

1. that gives bob the role of viewer on trip: Europe.
2. that gives alice the role of owner on trip: Europe.

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { OpenFgaApi } = require('@openfga/sdk');

// Initialize the SDK with no auth - see "How to setup SDK client" for more options
const fgaClient = new OpenFgaApi({
  apiScheme: process.env.FGA_API_SCHEME, // Either "http" or "https", defaults to "https"
  apiHost: process.env.FGA_API_HOST, // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
  storeId: process.env.FGA_STORE_ID, // Either "http" or "https", defaults to "https"
});

await fgaClient.write({
  writes: {
    tuple_keys: [
      // Add bob as viewer on trip:Europe
      { user: 'user:bob', relation: 'viewer', object: 'trip:Europe'},
      // Add alice as owner on trip:Europe
      { user: 'user:alice', relation: 'owner', object: 'trip:Europe'}
    ]
  },
  authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw" 
});

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    fgaSdk "github.com/openfga/go-sdk"
    "os"
)

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
        ApiScheme:      os.Getenv("FGA_SCHEME"), // Either "http" or "https", defaults to "https"
        ApiHost:        os.Getenv("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
        StoreId:        os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
    })

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

    fgaClient := fgaSdk.NewAPIClient(configuration)
}

body := fgaSdk.WriteRequest{
	Writes:  &fgaSdk.TupleKeys{
		TupleKeys: []fgaSdk.TupleKey { 
			{
				// Add bob as viewer on trip:Europe
				User: fgaSdk.PtrString("user:bob"),
				Relation: fgaSdk.PtrString("viewer"),
				Object: fgaSdk.PtrString("trip:Europe"),
			}, 
			{
				// Add alice as owner on trip:Europe
				User: fgaSdk.PtrString("user:alice"),
				Relation: fgaSdk.PtrString("owner"),
				Object: fgaSdk.PtrString("trip:Europe"),
			}, 
		},
	},
 	AuthorizationModelId: fgaSdk.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw")}

_, response, err := fgaClient.OpenFgaApi.Write(context.Background()).Body(body).Execute()
if err != nil {
    // .. Handle error
}

.NET

Initialize the SDK

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

namespace ExampleApp;

class MyProgram {
    static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new Configuration() {
          ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"), // Either "http" or "https", defaults to "https"
          ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        };
        var fgaClient = new OpenFgaApi(configuration);
    }
}

await fgaClient.Write(new WriteRequest{
  Writes = new TupleKeys(new List<TupleKey>() {
    // Add bob as viewer on trip:Europe
    new() { User = "user:bob", Relation = "viewer", Object = "trip:Europe" },
    // Add alice as owner on trip:Europe
    new() { User = "user:alice", Relation = "owner", Object = "trip:Europe" }
  }),
  AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
});

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import os
import json
import openfga_sdk
from openfga_sdk.api import open_fga_api

configuration = openfga_sdk.Configuration(
    api_scheme = os.environ.get('FGA_API_SCHEME'), # Either "http" or "https", defaults to "https"
    api_host = os.environ.get('FGA_API_HOST'), # required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
    store_id = os.environ.get('FGA_STORE_ID') # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
)

# Create an instance of the API class
fga_client_instance = open_fga_api.OpenFgaApi(openfga_sdk.ApiClient(configuration))

# from openfga_sdk.models.tuple_key import TupleKey
# from openfga_sdk.models.tuple_keys import TupleKeys
# from openfga_sdk.models.write_request import WriteRequest

async def write():
    body = WriteRequest(
        writes=TupleKeys(
            tuple_keys=[
                TupleKey(
                    # Add bob as viewer on trip:Europe
                    user="user:bob",
                    relation="viewer",
                    object="trip:Europe",
                ),
                TupleKey(
                    # Add alice as owner on trip:Europe
                    user="user:alice",
                    relation="owner",
                    object="trip:Europe",
                ),
            ],
        ),
 	authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw",
    )
    await fga_client_instance.write(body)

curl

Get the Bearer Token and set up the FGA_API_URL environment variable

Set FGA_API_URL according to the service you are using

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/write \
  -H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"writes": { "tuple_keys" : [{"user":"user:bob","relation":"viewer","object":"trip:Europe"},{"user":"user:alice","relation":"owner","object":"trip:Europe"}] }, "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

Pseudocode

write([
    // Add bob as viewer on trip:Europe
    {
      "user":"user:bob",
      "relation":"viewer",
      "object":"trip:Europe"
    },
    // Add alice as owner on trip:Europe
    {
      "user":"user:alice",
      "relation":"owner",
      "object":"trip:Europe"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

Now we can check: is bob allowed to view bookings on trip Europe?

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { OpenFgaApi } = require('@openfga/sdk');

// Initialize the SDK with no auth - see "How to setup SDK client" for more options
const fgaClient = new OpenFgaApi({
  apiScheme: process.env.FGA_API_SCHEME, // Either "http" or "https", defaults to "https"
  apiHost: process.env.FGA_API_HOST, // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
  storeId: process.env.FGA_STORE_ID, // Either "http" or "https", defaults to "https"
});

// Run a check
const { allowed } = await fgaClient.check({
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
  tuple_key: {
    user: 'user:bob',
    relation: 'booking_viewer',
    object: 'trip:Europe',
  },
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    fgaSdk "github.com/openfga/go-sdk"
    "os"
)

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
        ApiScheme:      os.Getenv("FGA_SCHEME"), // Either "http" or "https", defaults to "https"
        ApiHost:        os.Getenv("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
        StoreId:        os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
    })

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

    fgaClient := fgaSdk.NewAPIClient(configuration)
}

body := fgaSdk.CheckRequest{
	AuthorizationModelId: fgaSdk.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
	TupleKey: fgaSdk.TupleKey{
		User: "user:bob",
		Relation: "booking_viewer",
		Object: "trip:Europe",
	},
}
data, response, err := fgaClient.OpenFgaApi.Check(context.Background()).Body(body).Execute()

// data = { allowed: true }

.NET

Initialize the SDK

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

namespace ExampleApp;

class MyProgram {
    static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new Configuration() {
          ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"), // Either "http" or "https", defaults to "https"
          ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        };
        var fgaClient = new OpenFgaApi(configuration);
    }
}

// Run a check
var response = await fgaClient.Check(new CheckRequest
{
TupleKey = new TupleKey() {
  User = "user:bob",
  Relation = "booking_viewer",
  Object = "trip:Europe"
}, AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"});

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import os
import json
import openfga_sdk
from openfga_sdk.api import open_fga_api

configuration = openfga_sdk.Configuration(
    api_scheme = os.environ.get('FGA_API_SCHEME'), # Either "http" or "https", defaults to "https"
    api_host = os.environ.get('FGA_API_HOST'), # required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
    store_id = os.environ.get('FGA_STORE_ID') # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
)

# Create an instance of the API class
fga_client_instance = open_fga_api.OpenFgaApi(openfga_sdk.ApiClient(configuration))

# from openfga_sdk.models.check_request import CheckRequest
# from openfga_sdk.models.tuple_key import TupleKey
# from openfga_sdk.models.contextual_tuple_keys import ContextualTupleKeys

# Run a check
async def check():
    body = CheckRequest(
        tuple_key=TupleKey(
            user="user:bob",
            relation="booking_viewer",
            object="trip:Europe",
        ), 
        authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw",
    )
    response = await fga_client_instance.check(body)
    # response.allowed = true

curl

Get the Bearer Token and set up the FGA_API_URL environment variable

Set FGA_API_URL according to the service you are using

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
  -H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw", "tuple_key":{"user":"user:bob","relation":"booking_viewer","object":"trip:Europe"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:bob", // check if the user `user:bob`
  relation = "booking_viewer", // has an `booking_viewer` relation
  object = "trip:Europe", // with the object `trip:Europe`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

bob is a booking_viewer because of the following chain of resolution:

1. bob is a viewer on trip: Europe
2. Any user related to the object trip:Europe as viewer is also related as a booking_viewer (i.e usersRelatedToObjectAs: viewer)
3. Therefore, all viewers on a given trip are booking_viewers

To confirm that bob is not allowed to add bookings on trip Europe, we can do the following check:

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { OpenFgaApi } = require('@openfga/sdk');

// Initialize the SDK with no auth - see "How to setup SDK client" for more options
const fgaClient = new OpenFgaApi({
  apiScheme: process.env.FGA_API_SCHEME, // Either "http" or "https", defaults to "https"
  apiHost: process.env.FGA_API_HOST, // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
  storeId: process.env.FGA_STORE_ID, // Either "http" or "https", defaults to "https"
});

// Run a check
const { allowed } = await fgaClient.check({
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
  tuple_key: {
    user: 'user:bob',
    relation: 'booking_adder',
    object: 'trip:Europe',
  },
});

// allowed = false

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    fgaSdk "github.com/openfga/go-sdk"
    "os"
)

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
        ApiScheme:      os.Getenv("FGA_SCHEME"), // Either "http" or "https", defaults to "https"
        ApiHost:        os.Getenv("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
        StoreId:        os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
    })

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

    fgaClient := fgaSdk.NewAPIClient(configuration)
}

body := fgaSdk.CheckRequest{
	AuthorizationModelId: fgaSdk.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
	TupleKey: fgaSdk.TupleKey{
		User: "user:bob",
		Relation: "booking_adder",
		Object: "trip:Europe",
	},
}
data, response, err := fgaClient.OpenFgaApi.Check(context.Background()).Body(body).Execute()

// data = { allowed: false }

.NET

Initialize the SDK

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

namespace ExampleApp;

class MyProgram {
    static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new Configuration() {
          ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"), // Either "http" or "https", defaults to "https"
          ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        };
        var fgaClient = new OpenFgaApi(configuration);
    }
}

// Run a check
var response = await fgaClient.Check(new CheckRequest
{
TupleKey = new TupleKey() {
  User = "user:bob",
  Relation = "booking_adder",
  Object = "trip:Europe"
}, AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"});

// response.Allowed = false

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import os
import json
import openfga_sdk
from openfga_sdk.api import open_fga_api

configuration = openfga_sdk.Configuration(
    api_scheme = os.environ.get('FGA_API_SCHEME'), # Either "http" or "https", defaults to "https"
    api_host = os.environ.get('FGA_API_HOST'), # required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
    store_id = os.environ.get('FGA_STORE_ID') # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
)

# Create an instance of the API class
fga_client_instance = open_fga_api.OpenFgaApi(openfga_sdk.ApiClient(configuration))

# from openfga_sdk.models.check_request import CheckRequest
# from openfga_sdk.models.tuple_key import TupleKey
# from openfga_sdk.models.contextual_tuple_keys import ContextualTupleKeys

# Run a check
async def check():
    body = CheckRequest(
        tuple_key=TupleKey(
            user="user:bob",
            relation="booking_adder",
            object="trip:Europe",
        ), 
        authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw",
    )
    response = await fga_client_instance.check(body)
    # response.allowed = false

curl

Get the Bearer Token and set up the FGA_API_URL environment variable

Set FGA_API_URL according to the service you are using

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
  -H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw", "tuple_key":{"user":"user:bob","relation":"booking_adder","object":"trip:Europe"}}'

# Response: {"allowed":false}

Pseudocode

check(
  user = "user:bob", // check if the user `user:bob`
  relation = "booking_adder", // has an `booking_adder` relation
  object = "trip:Europe", // with the object `trip:Europe`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: false

We can also check: is alice allowed to view and add bookings on trip Europe?

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { OpenFgaApi } = require('@openfga/sdk');

// Initialize the SDK with no auth - see "How to setup SDK client" for more options
const fgaClient = new OpenFgaApi({
  apiScheme: process.env.FGA_API_SCHEME, // Either "http" or "https", defaults to "https"
  apiHost: process.env.FGA_API_HOST, // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
  storeId: process.env.FGA_STORE_ID, // Either "http" or "https", defaults to "https"
});

// Run a check
const { allowed } = await fgaClient.check({
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
  tuple_key: {
    user: 'user:alice',
    relation: 'booking_viewer',
    object: 'trip:Europe',
  },
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    fgaSdk "github.com/openfga/go-sdk"
    "os"
)

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
        ApiScheme:      os.Getenv("FGA_SCHEME"), // Either "http" or "https", defaults to "https"
        ApiHost:        os.Getenv("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
        StoreId:        os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
    })

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

    fgaClient := fgaSdk.NewAPIClient(configuration)
}

body := fgaSdk.CheckRequest{
	AuthorizationModelId: fgaSdk.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
	TupleKey: fgaSdk.TupleKey{
		User: "user:alice",
		Relation: "booking_viewer",
		Object: "trip:Europe",
	},
}
data, response, err := fgaClient.OpenFgaApi.Check(context.Background()).Body(body).Execute()

// data = { allowed: true }

.NET

Initialize the SDK

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

namespace ExampleApp;

class MyProgram {
    static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new Configuration() {
          ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"), // Either "http" or "https", defaults to "https"
          ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        };
        var fgaClient = new OpenFgaApi(configuration);
    }
}

// Run a check
var response = await fgaClient.Check(new CheckRequest
{
TupleKey = new TupleKey() {
  User = "user:alice",
  Relation = "booking_viewer",
  Object = "trip:Europe"
}, AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"});

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import os
import json
import openfga_sdk
from openfga_sdk.api import open_fga_api

configuration = openfga_sdk.Configuration(
    api_scheme = os.environ.get('FGA_API_SCHEME'), # Either "http" or "https", defaults to "https"
    api_host = os.environ.get('FGA_API_HOST'), # required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
    store_id = os.environ.get('FGA_STORE_ID') # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
)

# Create an instance of the API class
fga_client_instance = open_fga_api.OpenFgaApi(openfga_sdk.ApiClient(configuration))

# from openfga_sdk.models.check_request import CheckRequest
# from openfga_sdk.models.tuple_key import TupleKey
# from openfga_sdk.models.contextual_tuple_keys import ContextualTupleKeys

# Run a check
async def check():
    body = CheckRequest(
        tuple_key=TupleKey(
            user="user:alice",
            relation="booking_viewer",
            object="trip:Europe",
        ), 
        authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw",
    )
    response = await fga_client_instance.check(body)
    # response.allowed = true

curl

Get the Bearer Token and set up the FGA_API_URL environment variable

Set FGA_API_URL according to the service you are using

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
  -H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw", "tuple_key":{"user":"user:alice","relation":"booking_viewer","object":"trip:Europe"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:alice", // check if the user `user:alice`
  relation = "booking_viewer", // has an `booking_viewer` relation
  object = "trip:Europe", // with the object `trip:Europe`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { OpenFgaApi } = require('@openfga/sdk');

// Initialize the SDK with no auth - see "How to setup SDK client" for more options
const fgaClient = new OpenFgaApi({
  apiScheme: process.env.FGA_API_SCHEME, // Either "http" or "https", defaults to "https"
  apiHost: process.env.FGA_API_HOST, // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
  storeId: process.env.FGA_STORE_ID, // Either "http" or "https", defaults to "https"
});

// Run a check
const { allowed } = await fgaClient.check({
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
  tuple_key: {
    user: 'user:alice',
    relation: 'booking_adder',
    object: 'trip:Europe',
  },
});

// allowed = true

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    fgaSdk "github.com/openfga/go-sdk"
    "os"
)

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
        ApiScheme:      os.Getenv("FGA_SCHEME"), // Either "http" or "https", defaults to "https"
        ApiHost:        os.Getenv("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
        StoreId:        os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
    })

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

    fgaClient := fgaSdk.NewAPIClient(configuration)
}

body := fgaSdk.CheckRequest{
	AuthorizationModelId: fgaSdk.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
	TupleKey: fgaSdk.TupleKey{
		User: "user:alice",
		Relation: "booking_adder",
		Object: "trip:Europe",
	},
}
data, response, err := fgaClient.OpenFgaApi.Check(context.Background()).Body(body).Execute()

// data = { allowed: true }

.NET

Initialize the SDK

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

namespace ExampleApp;

class MyProgram {
    static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new Configuration() {
          ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"), // Either "http" or "https", defaults to "https"
          ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"), // required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        };
        var fgaClient = new OpenFgaApi(configuration);
    }
}

// Run a check
var response = await fgaClient.Check(new CheckRequest
{
TupleKey = new TupleKey() {
  User = "user:alice",
  Relation = "booking_adder",
  Object = "trip:Europe"
}, AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"});

// response.Allowed = true

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import os
import json
import openfga_sdk
from openfga_sdk.api import open_fga_api

configuration = openfga_sdk.Configuration(
    api_scheme = os.environ.get('FGA_API_SCHEME'), # Either "http" or "https", defaults to "https"
    api_host = os.environ.get('FGA_API_HOST'), # required, define without the scheme (e.g. api.openfga.example instead of https://api.openfga.example)
    store_id = os.environ.get('FGA_STORE_ID') # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
)

# Create an instance of the API class
fga_client_instance = open_fga_api.OpenFgaApi(openfga_sdk.ApiClient(configuration))

# from openfga_sdk.models.check_request import CheckRequest
# from openfga_sdk.models.tuple_key import TupleKey
# from openfga_sdk.models.contextual_tuple_keys import ContextualTupleKeys

# Run a check
async def check():
    body = CheckRequest(
        tuple_key=TupleKey(
            user="user:alice",
            relation="booking_adder",
            object="trip:Europe",
        ), 
        authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw",
    )
    response = await fga_client_instance.check(body)
    # response.allowed = true

curl

Get the Bearer Token and set up the FGA_API_URL environment variable

Set FGA_API_URL according to the service you are using

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
  -H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw", "tuple_key":{"user":"user:alice","relation":"booking_adder","object":"trip:Europe"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:alice", // check if the user `user:alice`
  relation = "booking_adder", // has an `booking_adder` relation
  object = "trip:Europe", // with the object `trip:Europe`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

alice is a booking_viewer and booking_adder because of the following chain of resolution:

1. alice is a owner on trip: Europe
2. Any user related to the object trip:Europe as owner is also related as a booking_viewer
3. Any user related to the object trip:Europe as owner is also related as a booking_adder
4. Therefore, all owners on a given trip are booking_viewers and booking_adders on that trip

caution

Note: Make sure to use unique ids for each object and user within your application domain when creating relationship tuples for OpenFGA. We are using first names and simple ids to just illustrate an easy-to-follow example.

Related Sections

Check the following sections for more on how to model for roles and permissions.

Modeling Concepts: Concentric Relationships

Learn about how to represent a concentric relationships in OpenFGA.

• More

Modeling Google Drive

See how to indicate that editors are commenters and viewers in Google Drive.

• More

Modeling GitHub

See how to indicate that repository admins are writers and readers in GitHub.

• More