--- title: "Custom Roles" description: "Modeling custom and dynamically changing roles in your system" canonical: "https://openfga.dev/docs/modeling/custom-roles" content_type: "documentation" last_updated: "2026-08-31T13:15:17.000Z" --- # Custom Roles In this guide you'll learn how to model custom roles in your system using [OpenFGA](https://openfga.dev/docs/fga.md). 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](https://openfga.dev/docs/modeling/roles-and-permissions.md). 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](https://openfga.dev/docs/concepts.md) and know how to develop the things listed below. ### Initial ModelTo start, let's say there is an application with a [type](https://openfga.dev/docs/concepts.md#what-is-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. ``` model schema 1.1 type user type asset-category relations define viewer: [user] or editor define editor: [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 →](https://openfga.dev/docs/modeling/user-groups.md) ### 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 →](https://openfga.dev/docs/modeling/building-blocks/object-to-object-relationships.md) ### Concepts & Configuration Language - [OpenFGA Concepts](https://openfga.dev/docs/concepts.md) - [Configuration Language](https://openfga.dev/docs/configuration-language.md) ## 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](/assets/images/custom-roles-roles-and-permissions-ca8254c87a37e52fea450bdeb634b39c.svg) 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](https://openfga.dev/docs/concepts.md#what-is-a-check-request) requests return the expected result. ![Image showing expected results](/assets/images/custom-roles-expectations-f015ffb4203247a03815859fb0844f95.svg) In order to do this, we need to: 1. Update the Authorization Model to add a Role Type 2. Use Relationship Tuples to tie the Users to the Roles 3. Use Relationship Tuples to associate Permissions with the Roles 4. 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: ``` 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] ``` 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: - Node.js - Go - .NET - Python - Java - curl - CLI - Pseudocode 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 }); ``` ``` const options = { authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA", }; await fgaClient.write({ writes: [ // Anne is assigned the media-manager role {"_description":"Anne is assigned the media-manager role","user":"user:anne","relation":"assignee","object":"role:media-manager"}, // Beth is assigned the media-viewer role {"_description":"Beth is assigned the media-viewer role","user":"user:beth","relation":"assignee","object":"role:media-viewer"} ], }, options); ``` 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: openfga.PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"), } body := ClientWriteRequest{ Writes: []ClientTupleKey{ { // 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", }, }, } data, err := fgaClient.Write(context.Background()). Body(body). Options(options). Execute() if err != nil { // .. Handle error } _ = data // use the response ``` 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() { // 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 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 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) ``` 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 assigned the media-manager role new ClientTupleKey() .user("user:anne") .relation("assignee") ._object("role:media-manager"), // Beth is assigned the media-viewer role new ClientTupleKey() .user("user:beth") .relation("assignee") ._object("role:media-viewer") )); var response = fgaClient.write(body, options).get(); ``` 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": "assignee", "object": "role:media-manager" }, { "user": "user:beth", "relation": "assignee", "object": "role:media-viewer" } ] }, "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA" }' ``` 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 assignee role:media-manager fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA 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" } ]) ``` We can verify they are members of said roles by issuing the following check requests: ![Image showing expected membership checks](/assets/images/custom-roles-membership-checks-057e971c8b2def87ea3c405352a0f100.svg) - Node.js - Go - .NET - Python - Java - CLI - curl - Pseudocode - Playground 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: 'assignee', object: 'role:media-manager', }, { authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA', }); // allowed = true ``` 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: openfga.PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"), } 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() { 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 = "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 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="assignee", object="role:media-manager", ) response = await fga_client.check(body, options) # response.allowed = true ``` 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("assignee") ._object("role:media-manager"); var response = fgaClient.check(body, options).get(); // response.getAllowed() = true ``` 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 assignee role:media-manager # Response: {"allowed":true} ``` 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": "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` ); Reply: true ``` ``` is user:anne related to role:media-manager as assignee? # Response: A green path from the user to the object indicating that the response from the API is `{"allowed":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). - Node.js - Go - .NET - Python - Java - curl - CLI - Pseudocode 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 }); ``` ``` const options = { authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA", }; await fgaClient.write({ writes: [ // Users assigned the media-manager role can edit in the Logos assets category {"_description":"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 {"_description":"Users assigned the media-viewer role can view from the Logos assets category","user":"role:media-viewer#assignee","relation":"viewer","object":"asset-category:logos"} ], }, options); ``` 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: openfga.PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"), } body := ClientWriteRequest{ Writes: []ClientTupleKey{ { // 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", }, }, } data, err := fgaClient.Write(context.Background()). Body(body). Options(options). Execute() if err != nil { // .. Handle error } _ = data // use the response ``` 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() { // 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 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( # 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) ``` 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( // Users assigned the media-manager role can edit in the Logos assets category new ClientTupleKey() .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 ClientTupleKey() .user("role:media-viewer#assignee") .relation("viewer") ._object("asset-category:logos") )); var response = fgaClient.write(body, options).get(); ``` 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": "role:media-manager#assignee", "relation": "editor", "object": "asset-category:logos" }, { "user": "role:media-viewer#assignee", "relation": "viewer", "object": "asset-category:logos" } ] }, "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA" }' ``` 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 role:media-manager#assignee editor asset-category:logos fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA 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" } ]) ``` ### 04. Verify That The Authorization Model Works To ensure our model works, it needs to match our expectations: ![Image showing expected results](/assets/images/custom-roles-expectations-f015ffb4203247a03815859fb0844f95.svg) - Node.js - Go - .NET - Python - Java - CLI - curl - Pseudocode - Playground 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: 'editor', object: 'asset-category:logos', }, { authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA', }); // allowed = true ``` 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: openfga.PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"), } 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() { 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 = "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 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="editor", object="asset-category:logos", ) response = await fga_client.check(body, options) # response.allowed = true ``` 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("editor") ._object("asset-category:logos"); var response = fgaClient.check(body, options).get(); // response.getAllowed() = true ``` 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 editor asset-category:logos # Response: {"allowed":true} ``` 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": "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` ); Reply: true ``` ``` is user:anne related to asset-category:logos as editor? # Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}` ``` The checks come back as we expect, so our model is working correctly. ## Related Sections Check the following sections for more on how to model with OpenFGA. **Modeling Roles and Permissions** Learn how to remove the direct relationship to indicate nonassignable permissions. - [More](https://openfga.dev/docs/modeling/roles-and-permissions.md) **Modeling Concepts: Object to Object Relationships** Learn about how to model object to object relationships in OpenFGA. - [More](https://openfga.dev/docs/modeling/building-blocks/object-to-object-relationships.md)