Modeling GitHub permissions with OpenFGA

This tutorial explains how to model GitHub's Organization permission model using OpenFGA. This article from the GitHub docs has links to all other articles we are going to be exploring in this document.

What you will learn

• Indicate relationships between a group of users and an object. See Modeling User Groups for more details.
  Used here to indicate that all members of an organization are repository admins on the organization.
• Modeling concentric relationship to have a certain relation on an object imply another relation on the same object. See Modeling Concepts: Concentric Relationships for more.
  Used here to indicate that maintainers of a repository are also writers of that repository.
• Using the union operator condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated.
  Used here to indicate that a user can be a reader on a repository, or can have the reader relationship implied through triager.
• Model parent-child objects to indicate that a user having a relationship with a certain object implies having a relationship with another object in OpenFGA.
  Used here to indicate that a repository admin on a GitHub organization, is an admin on all repositories that organization owns.

Before You Start

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

OpenFGA Concepts

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

Modeling Concentric Relationships

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

Modeling Object-to-Object Relationships

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

Used here to indicate that users who have repo admin access on an organization, have admin access to all repositories owned by that organization.

Concepts & Configuration Language

• Some OpenFGA Concepts
• Configuration Language

What You Will Be Modeling

GitHub is a system to develop and collaborate on code.

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

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

Requirements

GitHub's permission model is represented in their documentation.

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

Requirements:

• Users can be admins, maintainers, writers, triagers or readers of repositories (each level inherits all access of the level lower than it. e.g. admins inherit maintainer access and so forth)
• Teams can have members
• Organizations can have members
• Organizations can own repositories
• Users can have repository admin access on organizations, and thus have admin access to all repositories owned by that organization

Defined Scenarios

There will be the following users:

• Anne
• Beth
• Charles, a member of the contoso/engineering team
• Diane, a member of the contoso/protocols team
• Erik, a member of the contoso org

And these requirements:

• members of the contoso/protocols team are members of the contoso/engineering team
• members of the contoso org are repo_admins on the org
• repo admins on the org are admins on all the repos the org owns

There will be a:

• contoso/tooling repository, owned by the contoso org and of which Beth is a writer and Anne is a reader and members of the contoso/engineering team are admins

Modeling GitHub's Permissions

01. Permissions For Individuals In An Org

GitHub has 5 different permission levels for repositories:

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

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

DSL

model
  schema 1.1
type user
type repo
  relations
    define reader: [user]
    define triager: [user]
    define writer: [user]
    define maintainer: [user]
    define admin: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "repo",
      "relations": {
        "reader": {
          "this": {}
        },
        "triager": {
          "this": {}
        },
        "writer": {
          "this": {}
        },
        "maintainer": {
          "this": {}
        },
        "admin": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "reader": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "triager": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "maintainer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "admin": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

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

DSL

model
  schema 1.1
type user
type repo
  relations
    define reader: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "repo",
      "relations": {
        "reader": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "reader": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

info

Objects of type "repo" have users related to them as "reader" if those users belong to the userset of all users related to the repo as "reader"

If we want to say anne is a reader of repository repo:contoso/tooling we had create this relationship tuple:

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: [
      { user: 'user:anne', relation: 'reader', object: 'repo:contoso/tooling'}
    ]
  },
  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 { 
			{
				User: fgaSdk.PtrString("user:anne"),
				Relation: fgaSdk.PtrString("reader"),
				Object: fgaSdk.PtrString("repo:contoso/tooling"),
			}, 
		},
	},
 	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>() {
    new() { User = "user:anne", Relation = "reader", Object = "repo:contoso/tooling" }
  }),
  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(
                    user="user:anne",
                    relation="reader",
                    object="repo:contoso/tooling",
                ),
            ],
        ),
 	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:anne","relation":"reader","object":"repo:contoso/tooling"}] }, authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

Pseudocode

write([
    {
      "user":"user:anne",
      "relation":"reader",
      "object":"repo:contoso/tooling"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

We can now ask OpenFGA "is anne a reader of repository repo:contoso/tooling?"

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:anne',
    relation: 'reader',
    object: 'repo:contoso/tooling',
  },
});

// 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:anne",
		Relation: "reader",
		Object: "repo:contoso/tooling",
	},
}
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{TupleKey = new CheckRequest(new TupleKey() {
  User = "user:anne",
  Relation = "reader",
  Object = "repo:contoso/tooling"
}, 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:anne",
            relation="reader",
            object="repo:contoso/tooling",
        ), 
        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:anne","relation":"reader","object":"repo:contoso/tooling"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "reader", // has an `reader` relation
  object = "repo:contoso/tooling", // with the object `repo:contoso/tooling`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

We could also say that beth is a writer of the same repository:

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: [
      { user: 'user:beth', relation: 'writer', object: 'repo:contoso/tooling'}
    ]
  },
  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 { 
			{
				User: fgaSdk.PtrString("user:beth"),
				Relation: fgaSdk.PtrString("writer"),
				Object: fgaSdk.PtrString("repo:contoso/tooling"),
			}, 
		},
	},
 	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>() {
    new() { User = "user:beth", Relation = "writer", Object = "repo:contoso/tooling" }
  }),
  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(
                    user="user:beth",
                    relation="writer",
                    object="repo:contoso/tooling",
                ),
            ],
        ),
 	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:beth","relation":"writer","object":"repo:contoso/tooling"}] }, authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

Pseudocode

write([
    {
      "user":"user:beth",
      "relation":"writer",
      "object":"repo:contoso/tooling"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

And ask some questions to OpenFGA:

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:beth',
    relation: 'writer',
    object: 'repo:contoso/tooling',
  },
});

// 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:beth",
		Relation: "writer",
		Object: "repo:contoso/tooling",
	},
}
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{TupleKey = new CheckRequest(new TupleKey() {
  User = "user:beth",
  Relation = "writer",
  Object = "repo:contoso/tooling"
}, 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:beth",
            relation="writer",
            object="repo:contoso/tooling",
        ), 
        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:beth","relation":"writer","object":"repo:contoso/tooling"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:beth", // check if the user `user:beth`
  relation = "writer", // has an `writer` relation
  object = "repo:contoso/tooling", // with the object `repo:contoso/tooling`
   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:beth',
    relation: 'reader',
    object: 'repo:contoso/tooling',
  },
});

// 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:beth",
		Relation: "reader",
		Object: "repo:contoso/tooling",
	},
}
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{TupleKey = new CheckRequest(new TupleKey() {
  User = "user:beth",
  Relation = "reader",
  Object = "repo:contoso/tooling"
}, 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:beth",
            relation="reader",
            object="repo:contoso/tooling",
        ), 
        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:beth","relation":"reader","object":"repo:contoso/tooling"}}'

# Response: {"allowed":false}

Pseudocode

check(
  user = "user:beth", // check if the user `user:beth`
  relation = "reader", // has an `reader` relation
  object = "repo:contoso/tooling", // with the object `repo:contoso/tooling`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: false

The first reply makes sense but the second one does not. Intuitively, if beth was writer, she was also be a reader. In fact, GitHub explains this in their documentation

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

DSL

model
  schema 1.1
type user
type repo
  relations
    define reader: [user] or triager
    define triager: [user] or writer
    define writer: [user] or maintainer
    define maintainer: [user] or admin
    define admin: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "repo",
      "relations": {
        "reader": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "triager"
                }
              }
            ]
          }
        },
        "triager": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              }
            ]
          }
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "maintainer"
                }
              }
            ]
          }
        },
        "maintainer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "admin"
                }
              }
            ]
          }
        },
        "admin": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "reader": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "triager": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "maintainer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "admin": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

Let us examine one of those relations in detail:

DSL

type repo
  relations
    define reader: [user] or triager

JSON

{
  "type": "repo",
  "relations": {
    "reader": {
      "union": {
        "child": [
          {
            "this": {}
          },
          {
            "computedUserset": {
              "relation": "triager"
            }
          }
        ]
      }
    }
  },
  "metadata": {
    "relations": {
      "reader": {
        "directly_related_user_types": [
          {
            "type": "user"
          }
        ]
      }
    }
  }
}

info

The users with a reader relationship to a certain object of type "repo" are any of:

• the "readers": the set of users who are directly related to the repo as a "reader"
• the "triagers": the set of users who are related to the object as "triager"

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

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { 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:beth',
    relation: 'writer',
    object: 'repo:contoso/tooling',
  },
});

// 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:beth",
		Relation: "writer",
		Object: "repo:contoso/tooling",
	},
}
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{TupleKey = new CheckRequest(new TupleKey() {
  User = "user:beth",
  Relation = "writer",
  Object = "repo:contoso/tooling"
}, 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:beth",
            relation="writer",
            object="repo:contoso/tooling",
        ), 
        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:beth","relation":"writer","object":"repo:contoso/tooling"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:beth", // check if the user `user:beth`
  relation = "writer", // has an `writer` relation
  object = "repo:contoso/tooling", // with the object `repo:contoso/tooling`
   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:beth',
    relation: 'reader',
    object: 'repo:contoso/tooling',
  },
});

// 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:beth",
		Relation: "reader",
		Object: "repo:contoso/tooling",
	},
}
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{TupleKey = new CheckRequest(new TupleKey() {
  User = "user:beth",
  Relation = "reader",
  Object = "repo:contoso/tooling"
}, 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:beth",
            relation="reader",
            object="repo:contoso/tooling",
        ), 
        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:beth","relation":"reader","object":"repo:contoso/tooling"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:beth", // check if the user `user:beth`
  relation = "reader", // has an `reader` relation
  object = "repo:contoso/tooling", // with the object `repo:contoso/tooling`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

02. Permissions For Teams In An Org

GitHub also supports creating teams in an organization, adding members to a team and granting teams permissions, rather than individuals.

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

To add support for teams and memberships all we need to do is add this object to the OpenFGA authorization model:

DSL

model
  schema 1.1
type team
  relations
    define member: [user,team#member]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "team",
      "relations": {
        "member": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "member": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          }
        }
      }
    }
  ]
}

In addition, the repo's relations should be add team member as a directly related user types.

DSL

model
  schema 1.1
type user
type repo
  relations
    define reader: [user,team#member] or triager
    define triager: [user,team#member] or writer
    define writer: [user,team#member] or maintainer
    define maintainer: [user,team#member] or admin
    define admin: [user,team#member]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "repo",
      "relations": {
        "reader": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "triager"
                }
              }
            ]
          }
        },
        "triager": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              }
            ]
          }
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "maintainer"
                }
              }
            ]
          }
        },
        "maintainer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "admin"
                }
              }
            ]
          }
        },
        "admin": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "reader": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "triager": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "maintainer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "admin": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          }
        }
      }
    }
  ]
}

Let us now create a team, add a member to it and make it an admin of repo:contoso/tooling by adding the following relationship tuples:

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: [
      // make charles a member of the contoso/engineering team
      { user: 'user:charles', relation: 'member', object: 'team:contoso/engineering'},
      // make members of contoso/engineering team admins of contoso/tooling
      { user: 'team:contoso/engineering#member', relation: 'admin', object: 'repo:contoso/tooling'}
    ]
  },
  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 { 
			{
				// make charles a member of the contoso/engineering team
				User: fgaSdk.PtrString("user:charles"),
				Relation: fgaSdk.PtrString("member"),
				Object: fgaSdk.PtrString("team:contoso/engineering"),
			}, 
			{
				// make members of contoso/engineering team admins of contoso/tooling
				User: fgaSdk.PtrString("team:contoso/engineering#member"),
				Relation: fgaSdk.PtrString("admin"),
				Object: fgaSdk.PtrString("repo:contoso/tooling"),
			}, 
		},
	},
 	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>() {
    // make charles a member of the contoso/engineering team
    new() { User = "user:charles", Relation = "member", Object = "team:contoso/engineering" },
    // make members of contoso/engineering team admins of contoso/tooling
    new() { User = "team:contoso/engineering#member", Relation = "admin", Object = "repo:contoso/tooling" }
  }),
  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(
                    # make charles a member of the contoso/engineering team
                    user="user:charles",
                    relation="member",
                    object="team:contoso/engineering",
                ),
                TupleKey(
                    # make members of contoso/engineering team admins of contoso/tooling
                    user="team:contoso/engineering#member",
                    relation="admin",
                    object="repo:contoso/tooling",
                ),
            ],
        ),
 	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:charles","relation":"member","object":"team:contoso/engineering"},{"user":"team:contoso/engineering#member","relation":"admin","object":"repo:contoso/tooling"}] }, authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

Pseudocode

write([
    // make charles a member of the contoso/engineering team
    {
      "user":"user:charles",
      "relation":"member",
      "object":"team:contoso/engineering"
    },
    // make members of contoso/engineering team admins of contoso/tooling
    {
      "user":"team:contoso/engineering#member",
      "relation":"admin",
      "object":"repo:contoso/tooling"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

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

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { 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:charles',
    relation: 'admin',
    object: 'repo:contoso/tooling',
  },
});

// 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:charles",
		Relation: "admin",
		Object: "repo:contoso/tooling",
	},
}
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{TupleKey = new CheckRequest(new TupleKey() {
  User = "user:charles",
  Relation = "admin",
  Object = "repo:contoso/tooling"
}, 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:charles",
            relation="admin",
            object="repo:contoso/tooling",
        ), 
        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:charles","relation":"admin","object":"repo:contoso/tooling"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:charles", // check if the user `user:charles`
  relation = "admin", // has an `admin` relation
  object = "repo:contoso/tooling", // with the object `repo:contoso/tooling`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

03. Permissions For Child Teams In An Org

GitHub also supports team nesting, known as "child teams". Child teams inherit the access permissions of the parent team. Let's say we have a protocols team that is part of the engineering. The simplest way to achieve the aforementioned requirement is just adding this relationship tuple:

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: [
      { user: 'team:contoso/protocols#member', relation: 'member', object: 'team:contoso/engineering'}
    ]
  },
  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 { 
			{
				User: fgaSdk.PtrString("team:contoso/protocols#member"),
				Relation: fgaSdk.PtrString("member"),
				Object: fgaSdk.PtrString("team:contoso/engineering"),
			}, 
		},
	},
 	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>() {
    new() { User = "team:contoso/protocols#member", Relation = "member", Object = "team:contoso/engineering" }
  }),
  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(
                    user="team:contoso/protocols#member",
                    relation="member",
                    object="team:contoso/engineering",
                ),
            ],
        ),
 	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":"team:contoso/protocols#member","relation":"member","object":"team:contoso/engineering"}] }, authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

Pseudocode

write([
    {
      "user":"team:contoso/protocols#member",
      "relation":"member",
      "object":"team:contoso/engineering"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

which says that members of protocols are members of engineering.

Note: this is enough and valid for our current requirements, and for other read cases allows determining members of the direct team vs sub teams as the latter come from team:contoso/protocols#member. If the #member relation should not be followed for use cases a different approach could be taken.

We can now add a member to the protocols team and check that they are admins of the tooling repository.

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: [
      // make diane a member of the contoso/protocols team
      { user: 'user:diane', relation: 'member', object: 'team:contoso/protocols'}
    ]
  },
  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 { 
			{
				// make diane a member of the contoso/protocols team
				User: fgaSdk.PtrString("user:diane"),
				Relation: fgaSdk.PtrString("member"),
				Object: fgaSdk.PtrString("team:contoso/protocols"),
			}, 
		},
	},
 	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>() {
    // make diane a member of the contoso/protocols team
    new() { User = "user:diane", Relation = "member", Object = "team:contoso/protocols" }
  }),
  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(
                    # make diane a member of the contoso/protocols team
                    user="user:diane",
                    relation="member",
                    object="team:contoso/protocols",
                ),
            ],
        ),
 	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:diane","relation":"member","object":"team:contoso/protocols"}] }, authorization_model_id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw"}'

Pseudocode

write([
    // make diane a member of the contoso/protocols team
    {
      "user":"user:diane",
      "relation":"member",
      "object":"team:contoso/protocols"
    }
], authorization_model_id="1uHxCSuTP0VKPYSnkq1pbb1jeZw")

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:diane',
    relation: 'admin',
    object: 'repo:contoso/tooling',
  },
});

// 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:diane",
		Relation: "admin",
		Object: "repo:contoso/tooling",
	},
}
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{TupleKey = new CheckRequest(new TupleKey() {
  User = "user:diane",
  Relation = "admin",
  Object = "repo:contoso/tooling"
}, 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:diane",
            relation="admin",
            object="repo:contoso/tooling",
        ), 
        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:diane","relation":"admin","object":"repo:contoso/tooling"}}'

# Response: {"allowed":true}

Pseudocode

check(
  user = "user:diane", // check if the user `user:diane`
  relation = "admin", // has an `admin` relation
  object = "repo:contoso/tooling", // with the object `repo:contoso/tooling`
   authorization_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
);

Reply: true

At the end of this section ended with the following permissions represented:

04. Base Permissions For Org Members

In GitHub, "you can set base permissions that apply to all members of an organization when accessing any of the organization's repositories". For our purposes this means that if:

• and contoso has a repository tooling
• and contoso has configured base permission to be "write"

then erik has write permissions to tooling.

Let us model that!

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

We need to introduce the notion of organization as a type, user organization membership and repository ownership as a relation. - It is worth calling that before this addition we were able to represent almost the entire GitHub repo permissions without adding the notion of organization to OpenFGA. Identifiers for users, repositories and teams were all that was necessary. Let us add support for organizations and membership. Hopefully this feels familiar by now:

DSL

model
  schema 1.1
type organization
  relations
    define member: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "organization",
      "relations": {
        "member": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "member": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

And support for repositories having owners:

DSL

model
  schema 1.1
type repo
  relations
    define reader: [user,team#member] or triager
    define triager: [user,team#member] or writer
    define writer: [user,team#member] or maintainer
    define maintainer: [user,team#member] or admin
    define admin: [user,team#member]
    define owner: [organization]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "repo",
      "relations": {
        "reader": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "triager"
                }
              }
            ]
          }
        },
        "triager": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "writer"
                }
              }
            ]
          }
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "maintainer"
                }
              }
            ]
          }
        },
        "maintainer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "relation": "admin"
                }
              }
            ]
          }
        },
        "admin": {
          "this": {}
        },
        "owner": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "reader": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "triager": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "maintainer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "admin": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "team",
                "relation": "member"
              }
            ]
          },
          "owner": {
            "directly_related_user_types": [
              {
                "type": "organization"
              }
            ]
          }
        }
      }
    }
  ]
}

info

Note the added "owner" relation, indicating that organizations can own repositories.

We can now make Erik a member of contoso and make contoso own contoso/tooling:

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: [
      { user: 'user:erik', relation: 'member', object: 'organization:contoso'},
      { user: 'organization:contoso', relation: 'owner', object: 'repo:contoso/tooling'}
    ]
  },
  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 { 
			{
				User: fgaSdk.PtrString("user:erik"),
				Relation: fgaSdk.PtrString("member"),
				Object: fgaSdk.PtrString("organization:contoso"),