Modeling Basics

This article describes how to grant a user access to an object in Auth0 FGA.

When to use

Granting access with relationship tuples is a core part of Auth0 FGA. Without relationship tuples, any checks_ will fail. You should use:

authorization model to represent what relations are possible between the users and objects in the system
relationship tuples to represent the facts about the relationships between users and objects in your system.

Before you start

Familiarize yourself with Auth0 FGA Concepts to understand how to develop a relationship tuple and authorization model.

Assume that you have the following authorization model.
You have a type called document that can have a viewer and/or an editor.

model
  schema 1.1

type user

type document
  relations
    define viewer: [user]
    define editor: [user]

In addition, you will need to know the following:

Auth0 FGA Concepts

A Type: a class of objects that have similar characteristics
A User: an entity in the system that can be related to an object
A Relation: a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system
An Object: represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model
A Relationship Tuple: a grouping consisting of a user, a relation and an object stored in Auth0 FGA

Try this guide out on the Auth0 FGA Playground

Step By Step

For an application to understand that user x has access to document y, it must provide Auth0 Fine-Grained Authorization (FGA) that information with relationship tuples. Each relationship tuple has three basic parameters: a user, a relation and an object.

01. Create A Relationship Tuple

Below, you'll add a relationship tuple to indicate that bob is an editor of document:meeting_notes.doc by adding the following:

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
const { CredentialsMethod, OpenFgaClient } = require('@openfga/sdk'); // OR import { CredentialsMethod, OpenFgaClient } from '@openfga/sdk';

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

const fgaClient = new OpenFgaClient({
    apiUrl: process.env.FGA_API_URL,
    storeId: process.env.FGA_STORE_ID,
    authorizationModelId: process.env.FGA_MODEL_ID,
    credentials: { // Credentials are not needed if connecting to the Playground API
      method: CredentialsMethod.ClientCredentials,
      config: {
        apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER,
        apiAudience: process.env.FGA_API_AUDIENCE,
        clientId: process.env.FGA_CLIENT_ID,
        clientSecret: process.env.FGA_CLIENT_SECRET,
      },
    },
});

const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
};

await fgaClient.write({
  writes: [
      {"user":"user:bob","relation":"editor","object":"document:meeting_notes.doc"}
  ],
}, options);

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
import (
    "os"

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

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), 
        StoreId:              os.Getenv("FGA_STORE_ID"),
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
        Credentials: &credentials.Credentials{ // Credentials are not needed if connecting to the Playground API
            Method: credentials.CredentialsMethodClientCredentials,
            Config: &credentials.Config{
                ClientCredentialsClientId:       os.Getenv("FGA_CLIENT_ID"),
                ClientCredentialsClientSecret:   os.Getenv("FGA_CLIENT_SECRET"),
                ClientCredentialsApiAudience:    os.Getenv("FGA_API_AUDIENCE"),
                ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
            },
        },
    })

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

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

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             User: "user:bob",
             Relation: "editor",
             Object: "document:meeting_notes.doc",
        }, 
    }, 
}

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

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

_ = data // use the response

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

class MyProgram {
    static async Task Main() {
        var configuration = new ClientConfiguration() {
            ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
            StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
            AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
            Credentials = new Credentials() { // Credentials are not needed if connecting to the Playground API
                Method = CredentialsMethod.ClientCredentials,
                Config = new CredentialsConfig() {
                    ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
                    ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
                    ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
                    ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
                }
            }
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
       new() {
                  User = "user:bob",
                  Relation = "editor",
                  Object = "document:meeting_notes.doc"
              }
  },
};
var response = await fgaClient.Write(body, options);

Initialize the SDK

# Checkout the "How to Setup the SDK Client" page for more details.

import os
import openfga_sdk
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
# FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
# FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
# FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
# FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

async def main():
    credentials = Credentials(
      method='client_credentials',
      configuration=CredentialConfiguration(
          api_issuer= os.environ.get('FGA_API_TOKEN_ISSUER'),
          api_audience= os.environ.get('FGA_API_AUDIENCE'),
          client_id= os.environ.get('FGA_CLIENT_ID'),
          client_secret= os.environ.get('FGA_CLIENT_SECRET'),
      )
    )

    configuration = ClientConfiguration(
        api_url = os.environ.get('FGA_API_URL'), # required, e.g. https://api.fga.example
        store_id = os.environ.get('FGA_STORE_ID'), # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        authorization_model_id = os.environ.get('FGA_MODEL_ID'), # Optional, can be overridden per request
    )

    # Enter a context with an instance of the OpenFgaClient
    async with OpenFgaClient(configuration) as fga_client:
        api_response = await fga_client.read_authorization_models()
        await fga_client.close()

asyncio.run(main())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    user="user:bob",
                    relation="editor",
                    object="document:meeting_notes.doc",
                ),
        ],
)

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;
import dev.openfga.sdk.api.configuration.ClientCredentials;
import dev.openfga.sdk.api.configuration.Credentials;

// FGA_API_URL = 'https://api.us1.fga.dev' for Dev Preview and Early Access / 'https://api.playground.fga.dev' for the FGA Playground
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

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_MODEL_ID")) // Optional, can be overridden per request
              .credentials(new Credentials(
                  new ClientCredentials()
                          .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
                          .apiAudience(System.getenv("FGA_API_AUDIENCE"))
                          .clientId(System.getenv("FGA_CLIENT_ID"))
                          .clientSecret(System.getenv("FGA_CLIENT_SECRET"))
              ));

      var fgaClient = new OpenFgaClient(config);
  }
}

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

var body = new ClientWriteRequest()
        .writes(List.of(
                new ClientTupleKey()
                        .user("user:bob")
                        .relation("editor")
                        ._object("document:meeting_notes.doc")
        ));

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

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

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:bob",
        "relation": "editor",
        "object": "document:meeting_notes.doc"
      }
    ]
  },
  "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}'

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:bob editor document:meeting_notes.doc  

write([
    {
      "user":"user:bob",
      "relation":"editor",
      "object":"document:meeting_notes.doc"
    }
])

02. Check That The Relationship Exists

Once you add that relationship tuple to Auth0 FGA, you can check if the relationship is valid by asking if bob is an editor of document:meeting_notes.doc:

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
const { CredentialsMethod, OpenFgaClient } = require('@openfga/sdk'); // OR import { CredentialsMethod, OpenFgaClient } from '@openfga/sdk';

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

const fgaClient = new OpenFgaClient({
    apiUrl: process.env.FGA_API_URL,
    storeId: process.env.FGA_STORE_ID,
    authorizationModelId: process.env.FGA_MODEL_ID,
    credentials: { // Credentials are not needed if connecting to the Playground API
      method: CredentialsMethod.ClientCredentials,
      config: {
        apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER,
        apiAudience: process.env.FGA_API_AUDIENCE,
        clientId: process.env.FGA_CLIENT_ID,
        clientSecret: process.env.FGA_CLIENT_SECRET,
      },
    },
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:bob',
    relation: 'editor',
    object: 'document:meeting_notes.doc',
  }, {
    authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
import (
    "os"

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

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), 
        StoreId:              os.Getenv("FGA_STORE_ID"),
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
        Credentials: &credentials.Credentials{ // Credentials are not needed if connecting to the Playground API
            Method: credentials.CredentialsMethodClientCredentials,
            Config: &credentials.Config{
                ClientCredentialsClientId:       os.Getenv("FGA_CLIENT_ID"),
                ClientCredentialsClientSecret:   os.Getenv("FGA_CLIENT_SECRET"),
                ClientCredentialsApiAudience:    os.Getenv("FGA_API_AUDIENCE"),
                ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
            },
        },
    })

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

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

body := ClientCheckRequest{
    User:     "user:bob",
    Relation: "editor",
    Object:   "document:meeting_notes.doc",
}

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

// data = { allowed: true }

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

class MyProgram {
    static async Task Main() {
        var configuration = new ClientConfiguration() {
            ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
            StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
            AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
            Credentials = new Credentials() { // Credentials are not needed if connecting to the Playground API
                Method = CredentialsMethod.ClientCredentials,
                Config = new CredentialsConfig() {
                    ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
                    ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
                    ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
                    ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
                }
            }
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA"
};
var body = new ClientCheckRequest {
    User = "user:bob",
    Relation = "editor",
    Object = "document:meeting_notes.doc",
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Initialize the SDK

# Checkout the "How to Setup the SDK Client" page for more details.

import os
import openfga_sdk
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
# FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
# FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
# FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
# FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

async def main():
    credentials = Credentials(
      method='client_credentials',
      configuration=CredentialConfiguration(
          api_issuer= os.environ.get('FGA_API_TOKEN_ISSUER'),
          api_audience= os.environ.get('FGA_API_AUDIENCE'),
          client_id= os.environ.get('FGA_CLIENT_ID'),
          client_secret= os.environ.get('FGA_CLIENT_SECRET'),
      )
    )

    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:bob",
    relation="editor",
    object="document:meeting_notes.doc",
)

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;
import dev.openfga.sdk.api.configuration.ClientCredentials;
import dev.openfga.sdk.api.configuration.Credentials;

// FGA_API_URL = 'https://api.us1.fga.dev' for Dev Preview and Early Access / 'https://api.playground.fga.dev' for the FGA Playground
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

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_MODEL_ID")) // Optional, can be overridden per request
              .credentials(new Credentials(
                  new ClientCredentials()
                          .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
                          .apiAudience(System.getenv("FGA_API_AUDIENCE"))
                          .clientId(System.getenv("FGA_CLIENT_ID"))
                          .clientSecret(System.getenv("FGA_CLIENT_SECRET"))
              ));

      var fgaClient = new OpenFgaClient(config);
  }
}

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

var body = new ClientCheckRequest()
        .user("user:bob")
        .relation("editor")
        ._object("document:meeting_notes.doc");

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

// response.getAllowed() = true 

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:bob editor document:meeting_notes.doc

# Response: {"allowed":true}

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

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:bob",
      "relation": "editor",
      "object": "document:meeting_notes.doc"
    }
  }'

# Response: {"allowed": true}

check(
  user = "user:bob", // check if the user `user:bob`
  relation = "editor", // has an `editor` relation
  object = "document:meeting_notes.doc", // with the object `document:meeting_notes.doc`
);

Reply: true

is user:bob related to document:meeting_notes.doc as editor?

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

Checking whether bob is an viewer of document:meeting_notes.doc returns false because that relationship tuple does not exist in Auth0 FGA yet.

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
const { CredentialsMethod, OpenFgaClient } = require('@openfga/sdk'); // OR import { CredentialsMethod, OpenFgaClient } from '@openfga/sdk';

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

const fgaClient = new OpenFgaClient({
    apiUrl: process.env.FGA_API_URL,
    storeId: process.env.FGA_STORE_ID,
    authorizationModelId: process.env.FGA_MODEL_ID,
    credentials: { // Credentials are not needed if connecting to the Playground API
      method: CredentialsMethod.ClientCredentials,
      config: {
        apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER,
        apiAudience: process.env.FGA_API_AUDIENCE,
        clientId: process.env.FGA_CLIENT_ID,
        clientSecret: process.env.FGA_CLIENT_SECRET,
      },
    },
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:bob',
    relation: 'viewer',
    object: 'document:meeting_notes.doc',
  }, {
    authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = false

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
import (
    "os"

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

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), 
        StoreId:              os.Getenv("FGA_STORE_ID"),
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
        Credentials: &credentials.Credentials{ // Credentials are not needed if connecting to the Playground API
            Method: credentials.CredentialsMethodClientCredentials,
            Config: &credentials.Config{
                ClientCredentialsClientId:       os.Getenv("FGA_CLIENT_ID"),
                ClientCredentialsClientSecret:   os.Getenv("FGA_CLIENT_SECRET"),
                ClientCredentialsApiAudience:    os.Getenv("FGA_API_AUDIENCE"),
                ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
            },
        },
    })

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

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

body := ClientCheckRequest{
    User:     "user:bob",
    Relation: "viewer",
    Object:   "document:meeting_notes.doc",
}

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

// data = { allowed: false }

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

class MyProgram {
    static async Task Main() {
        var configuration = new ClientConfiguration() {
            ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
            StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
            AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
            Credentials = new Credentials() { // Credentials are not needed if connecting to the Playground API
                Method = CredentialsMethod.ClientCredentials,
                Config = new CredentialsConfig() {
                    ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
                    ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
                    ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
                    ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
                }
            }
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

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

// response.Allowed = false

Initialize the SDK

# Checkout the "How to Setup the SDK Client" page for more details.

import os
import openfga_sdk
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
# FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
# FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
# FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
# FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

async def main():
    credentials = Credentials(
      method='client_credentials',
      configuration=CredentialConfiguration(
          api_issuer= os.environ.get('FGA_API_TOKEN_ISSUER'),
          api_audience= os.environ.get('FGA_API_AUDIENCE'),
          client_id= os.environ.get('FGA_CLIENT_ID'),
          client_secret= os.environ.get('FGA_CLIENT_SECRET'),
      )
    )

    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:bob",
    relation="viewer",
    object="document:meeting_notes.doc",
)

response = await fga_client.check(body, options)

# response.allowed = false

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import dev.openfga.sdk.api.configuration.ClientCredentials;
import dev.openfga.sdk.api.configuration.Credentials;

// FGA_API_URL = 'https://api.us1.fga.dev' for Dev Preview and Early Access / 'https://api.playground.fga.dev' for the FGA Playground
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

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_MODEL_ID")) // Optional, can be overridden per request
              .credentials(new Credentials(
                  new ClientCredentials()
                          .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
                          .apiAudience(System.getenv("FGA_API_AUDIENCE"))
                          .clientId(System.getenv("FGA_CLIENT_ID"))
                          .clientSecret(System.getenv("FGA_CLIENT_SECRET"))
              ));

      var fgaClient = new OpenFgaClient(config);
  }
}

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

var body = new ClientCheckRequest()
        .user("user:bob")
        .relation("viewer")
        ._object("document:meeting_notes.doc");

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

// response.getAllowed() = false 

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:bob viewer document:meeting_notes.doc

# Response: {"allowed":false}

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

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:bob",
      "relation": "viewer",
      "object": "document:meeting_notes.doc"
    }
  }'

# Response: {"allowed": false}

check(
  user = "user:bob", // check if the user `user:bob`
  relation = "viewer", // has an `viewer` relation
  object = "document:meeting_notes.doc", // with the object `document:meeting_notes.doc`
);

Reply: false

is user:bob related to document:meeting_notes.doc as viewer?

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

caution

When creating relationship tuples for Auth0 Fine-Grained Authorization (FGA), use unique ids for each object and user within your application domain. We're using first names and simple ids to as an easy-to-follow example.

FGA Concepts

Learn about the FGA Concepts.

Modeling: Getting Started

Learn about how to get started with modeling.

Configuration Language

Learn about Auth0 FGA Configuration Language.

Modeling Basics

Before you start

Auth0 FGA Concepts

The Playground

Step By Step

01. Create A Relationship Tuple

02. Check That The Relationship Exists

Have Feedback?

Before you start​

Auth0 FGA Concepts​

The Playground

Step By Step​

01. Create A Relationship Tuple​

02. Check That The Relationship Exists​

Related Sections​

Have Feedback?

Before you start

Auth0 FGA Concepts

Step By Step

01. Create A Relationship Tuple

02. Check That The Relationship Exists

Related Sections