Custom Roles

In this guide you'll learn how to model custom roles in your system using OpenFGA.

For example, a Business-to-Business (B2B) application could allow customers to create their own custom roles on the application to grant their users.

When to use

In many cases, roles would fit in well as relations on an object type, as seen in [Modeling Roles and Permissions](/docs/modeling/roles-and-permissions). In some cases, however, they may not be enough. Custom roles are useful when: - Users of the application are able to create arbitrary sets of roles with different permissions that govern the users' access to objects. - It is not known beforehand (at the time of Authorization Model creation) what the application roles are. - The team responsible for building the authorization model is different from the teams responsible for defining roles and access to the application.

Before you start

Before you start this guide, make sure you're familiar with some OpenFGA Concepts and know how to develop the things listed below.

Initial Model

To start, let's say there is an application with a type called asset-category. Users can have view and/or edit access to assets in that category. Any user who can edit can also view.

We'll start with the following authorization model showing a system with an asset-category type. This type allows users to have view and edit access to it.

DSL
JSON

model
  schema 1.1

type user

type asset-category
  relations
    define viewer: [user] or editor
    define editor: [user]

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "asset-category",
      "relations": {
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "editor"
                }
              }
            ]
          }
        },
        "editor": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "editor": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

In addition, you'll need to know the following:

Modeling Roles and Permissions

You need to know how to add users to groups and grant groups access to resources. 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 →

Concepts & Configuration Language

Step By Step

Starting with the authorization model mentioned above, we want to enable users to create their own custom roles, and tie permissions to those roles to our two users and to the permissions on the logo asset category.

For this guide, we'll model a scenario where a certain organization using our app has created an asset-category called "logos", and another called "text content".

The company administrator would like to create:

a media-manager role that allows users to edit assets in the logos asset category
a media-viewer role that allows users to view all assets in the logos asset category
a blog-editor role that allows users to edit all assets in the text content asset category
a blog-viewer role that allows users to view all assets in the text content asset category

Imagine these are what the permissions the roles in one organization using our service are like:

Image showing custom roles and permissions

Finally, the administrator wants to assign Anne the media-manager role and Beth the media-viewer role.

At the end, we'll verify our model by ensuring the following access check requests return the expected result.

Image showing expected results

In order to do this, we need to:

Update the Authorization Model to add a Role Type
Use Relationship Tuples to tie the Users to the Roles
Use Relationship Tuples to associate Permissions with the Roles
Verify that the Authorization Model works

01. Update The Authorization Model To Add A Role Type

Because our roles are going to be dynamic and might change frequently, we represent them in a new type instead of as relations on that same type. We'll create new type called role, where users can be related as assignee to it.

The authorization model becomes this:

DSL
JSON

model
  schema 1.1

type user

type asset-category
  relations
    define viewer: [user, role#assignee] or editor
    define editor: [user, role#assignee]

type role
  relations
    define assignee: [user]

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "asset-category",
      "relations": {
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "editor"
                }
              }
            ]
          }
        },
        "editor": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "role",
                "relation": "assignee"
              }
            ]
          },
          "editor": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "role",
                "relation": "assignee"
              }
            ]
          }
        }
      }
    },
    {
      "type": "role",
      "relations": {
        "assignee": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "assignee": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

With this change we can add relationship tuples indicating that a certain user is assigned a certain role.

02.Use Relationship Tuples To Tie The Users To The Roles

Once we've added the role type, we can assign roles to Anne and Beth. Anne is assigned the "media-manager" role and Beth is assigned the "media-viewer" role. We can do that by adding relationship tuples as follows:

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({
  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.fga.example instead of 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 assigned the media-manager role
      { user: 'user:anne', relation: 'assignee', object: 'role:media-manager'},
      // Beth is assigned the media-viewer role
      { user: 'user:beth', relation: 'assignee', object: 'role:media-viewer'}]
  },
}, {
  authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw" 
});

Initialize the SDK

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        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.fga.example instead of 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: openfga.PtrString(os.Getenv("FGA_MODEL_ID")),  // Optional, can be overridden per request
    })

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

options := ClientWriteOptions{
	AuthorizationModelId: openfga.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
}
body := fgaClient.ClientWriteRequest{
	Writes: &[]ClientTupleKey{
			{
				// Anne is assigned the media-manager role
				User: openfga.PtrString("user:anne"),
				Relation: openfga.PtrString("assignee"),
				Object: openfga.PtrString("role:media-manager"),
			}, 
			{
				// Beth is assigned the media-viewer role
				User: openfga.PtrString("user:beth"),
				Relation: openfga.PtrString("assignee"),
				Object: openfga.PtrString("role:media-viewer"),
			}, } }
data, err := fgaClient.Write(context.Background()).Body(requestBody).Options(options).Execute()

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

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() {
          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.fga.example instead of 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 ClientListObjectsOptions {
    AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
    // Anne is assigned the media-manager role
    new() { User = "user:anne", Relation = "assignee", Object = "role:media-manager" },
    // Beth is assigned the media-viewer role
    new() { User = "user:beth", Relation = "assignee", Object = "role:media-viewer" }
  },
};
var response = await fgaClient.Write(body, options);

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

configuration = ClientConfiguration(
    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.fga.example instead of 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()

options = {
    "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    # Anne is assigned the media-manager role
                    user="user:anne",
                    relation="assignee",
                    object="role:media-manager",
                ),
                ClientTuple(
                    # Beth is assigned the media-viewer role
                    user="user:beth",
                    relation="assignee",
                    object="role:media-viewer",
                ),
        ],

)

response = await fga_client.write(body, options)

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

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

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

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

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

fga tuple write --store-id=${FGA_STORE_ID} --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw user:anne assignee role:media-manager
fga tuple write --store-id=${FGA_STORE_ID} --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw user:beth assignee role:media-viewer

write([
    // Anne is assigned the media-manager role
    {
      "user":"user:anne",
      "relation":"assignee",
      "object":"role:media-manager"
    },
    // Beth is assigned the media-viewer role
    {
      "user":"user:beth",
      "relation":"assignee",
      "object":"role:media-viewer"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

We can verify they are members of said roles by issuing the following check requests:

Image showing expected membership checks

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({
  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.fga.example instead of 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: 'assignee',
    object: 'role:media-manager',
}, {
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
});

// allowed = true

Initialize the SDK

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        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.fga.example instead of 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: openfga.PtrString(os.Getenv("FGA_MODEL_ID")),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
	AuthorizationModelId: openfga.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
}
body := ClientCheckRequest{
	User:     "user:anne",
	Relation: "assignee",
	Object:   "role:media-manager",
}

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

// data = { allowed: true }

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() {
          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.fga.example instead of 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 = "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "assignee",
    Object = "role:media-manager",
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

configuration = ClientConfiguration(
    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.fga.example instead of 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()

options = {
    "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
}
body = ClientCheckRequest(
    user="user:anne",
    relation="assignee",
    object="role:media-manager",
)

response = await fga_client.check(body, options)

# response.allowed = true

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

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

fga query check --store-id=$FGA_STORE_ID --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw user:anne assignee role:media-manager

# Response: {"allowed":true}

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

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

curl -X POST $FGA_SERVER_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": "1uHxCSuTP0VKPYSnkq1pbb1jeZw", "tuple_key":{"user":"user:anne","relation":"assignee","object":"role:media-manager"}}'

# Response: {"allowed":true}

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "assignee", // has an `assignee` relation
  object = "role:media-manager", // with the object `role:media-manager`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

03. Use Relationship Tuples To Associate Permissions With The Roles

With our users and roles set up, we still need to tie members of a certain role to it's corresponding permission(s).

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({
  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.fga.example instead of 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: [
      // Users assigned the media-manager role can edit in the Logos assets category
      { user: 'role:media-manager#assignee', relation: 'editor', object: 'asset-category:logos'},
      // Users assigned the media-viewer role can view from the Logos assets category
      { user: 'role:media-viewer#assignee', relation: 'viewer', object: 'asset-category:logos'}]
  },
}, {
  authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw" 
});

Initialize the SDK

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        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.fga.example instead of 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: openfga.PtrString(os.Getenv("FGA_MODEL_ID")),  // Optional, can be overridden per request
    })

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

options := ClientWriteOptions{
	AuthorizationModelId: openfga.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
}
body := fgaClient.ClientWriteRequest{
	Writes: &[]ClientTupleKey{
			{
				// Users assigned the media-manager role can edit in the Logos assets category
				User: openfga.PtrString("role:media-manager#assignee"),
				Relation: openfga.PtrString("editor"),
				Object: openfga.PtrString("asset-category:logos"),
			}, 
			{
				// Users assigned the media-viewer role can view from the Logos assets category
				User: openfga.PtrString("role:media-viewer#assignee"),
				Relation: openfga.PtrString("viewer"),
				Object: openfga.PtrString("asset-category:logos"),
			}, } }
data, err := fgaClient.Write(context.Background()).Body(requestBody).Options(options).Execute()

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

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() {
          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.fga.example instead of 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 ClientListObjectsOptions {
    AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
    // Users assigned the media-manager role can edit in the Logos assets category
    new() { User = "role:media-manager#assignee", Relation = "editor", Object = "asset-category:logos" },
    // Users assigned the media-viewer role can view from the Logos assets category
    new() { User = "role:media-viewer#assignee", Relation = "viewer", Object = "asset-category:logos" }
  },
};
var response = await fgaClient.Write(body, options);

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

configuration = ClientConfiguration(
    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.fga.example instead of 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()

options = {
    "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    # Users assigned the media-manager role can edit in the Logos assets category
                    user="role:media-manager#assignee",
                    relation="editor",
                    object="asset-category:logos",
                ),
                ClientTuple(
                    # Users assigned the media-viewer role can view from the Logos assets category
                    user="role:media-viewer#assignee",
                    relation="viewer",
                    object="asset-category:logos",
                ),
        ],

)

response = await fga_client.write(body, options)

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

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

curl -X POST $FGA_SERVER_URL/stores/$FGA_STORE_ID/write \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"writes": { "tuple_keys" : [{"user":"role:media-manager#assignee","relation":"editor","object":"asset-category:logos"},{"user":"role:media-viewer#assignee","relation":"viewer","object":"asset-category:logos"}] }, "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

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

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

fga tuple write --store-id=${FGA_STORE_ID} --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw role:media-manager#assignee editor asset-category:logos
fga tuple write --store-id=${FGA_STORE_ID} --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw role:media-viewer#assignee viewer asset-category:logos

write([
    // Users assigned the media-manager role can edit in the Logos assets category
    {
      "user":"role:media-manager#assignee",
      "relation":"editor",
      "object":"asset-category:logos"
    },
    // Users assigned the media-viewer role can view from the Logos assets category
    {
      "user":"role:media-viewer#assignee",
      "relation":"viewer",
      "object":"asset-category:logos"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

04. Verify That The Authorization Model Works

To ensure our model works, it needs to match our expectations:

Image showing expected results

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({
  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.fga.example instead of 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: 'editor',
    object: 'asset-category:logos',
}, {
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
});

// allowed = true

Initialize the SDK

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        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.fga.example instead of 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: openfga.PtrString(os.Getenv("FGA_MODEL_ID")),  // Optional, can be overridden per request
    })

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

options := ClientCheckOptions{
	AuthorizationModelId: openfga.PtrString("1uHxCSuTP0VKPYSnkq1pbb1jeZw"),
}
body := ClientCheckRequest{
	User:     "user:anne",
	Relation: "editor",
	Object:   "asset-category:logos",
}

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

// data = { allowed: true }

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() {
          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.fga.example instead of 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 = "1uHxCSuTP0VKPYSnkq1pbb1jeZw",
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "editor",
    Object = "asset-category:logos",
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

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

configuration = ClientConfiguration(
    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.fga.example instead of 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()

options = {
    "authorization_model_id": "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
}
body = ClientCheckRequest(
    user="user:anne",
    relation="editor",
    object="asset-category:logos",
)

response = await fga_client.check(body, options)

# response.allowed = true

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

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

fga query check --store-id=$FGA_STORE_ID --model-id=1uHxCSuTP0VKPYSnkq1pbb1jeZw user:anne editor asset-category:logos

# Response: {"allowed":true}

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

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

curl -X POST $FGA_SERVER_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": "1uHxCSuTP0VKPYSnkq1pbb1jeZw", "tuple_key":{"user":"user:anne","relation":"editor","object":"asset-category:logos"}}'

# Response: {"allowed":true}

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "editor", // has an `editor` relation
  object = "asset-category:logos", // with the object `asset-category:logos`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

The checks come back as we expect, so our model is working correctly.

Modeling Roles and Permissions

Learn how to remove the direct relationship to indicate nonassignable permissions.

Modeling Concepts: Object to Object Relationships

Learn about how to model object to object relationships in OpenFGA.

Custom Roles

Before you start​

Initial Model​

Modeling Roles and Permissions​

Modeling Object-to-Object Relationships​

Concepts & Configuration Language​

Step By Step​

01. Update The Authorization Model To Add A Role Type​

02.Use Relationship Tuples To Tie The Users To The Roles​

03. Use Relationship Tuples To Associate Permissions With The Roles​

04. Verify That The Authorization Model Works​

Related Sections​

Before you start

Initial Model

Modeling Roles and Permissions

Modeling Object-to-Object Relationships

Concepts & Configuration Language

Step By Step

01. Update The Authorization Model To Add A Role Type

02.Use Relationship Tuples To Tie The Users To The Roles

03. Use Relationship Tuples To Associate Permissions With The Roles

04. Verify That The Authorization Model Works

Related Sections