How to perform a check

note

Auth0 Fine Grained Authorization (FGA) is the early-stage product we are building at Auth0 to solve fine-grained authorization at scale. Sign up for the Developer Community Preview to try it out, and join our Discord community if you are interested in learning more about our plans.

Please note that at this point in time, it is not considered production-ready and does not come with any SLAs; availability and uptime are not guaranteed. Limitations of Auth0 FGA during the Developer Community Preview can be found here.

This section will illustrate how to perform a check request to determine whether a user has a certain relationship with an object.

Before you start

Node.js

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_ENVIRONMENT, FGA_STORE_ID, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

Go

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_ENVIRONMENT, FGA_STORE_ID, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

.NET

1. You have obtained the environment, store id, client id and client secret.
2. You have installed the SDK.
3. You have configured the authorization model and updated the relationship tuples.
4. You have loaded FGA_ENVIRONMENT, FGA_STORE_ID, FGA_CLIENT_ID and FGA_CLIENT_SECRET as environment variables.

curl

1. You have obtained the environment, store id, client id and client secret.
2. You have configured the authorization model and updated the relationship tuples.
3. You have loaded FGA_ENVIRONMENT, FGA_BEARER_TOKEN and FGA_STORE_ID as environment variables.

Step by Step

Assume that you want to check whether user anne has relationship reader with object document:Z

01. Configure the Auth0 FGA API client

Before calling the check API, you will need to configure the API client.

Node.js

// import the SDK
const { Auth0FgaApi } = require('@auth0/fga');

// Initialize the SDK
const fgaClient = new Auth0FgaApi({
  environment: process.env.FGA_ENVIRONMENT,
  storeId: process.env.FGA_STORE_ID,
  clientId: process.env.FGA_CLIENT_ID,
  clientSecret: process.env.FGA_CLIENT_SECRET,
});

Go

import (
    fgaSdk "github.com/auth0-lab/fga-go-sdk"
    "os"
)

func Main() {
    configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
        Environment:  os.Getenv("FGA_ENVIRONMENT"),
        StoreId:      os.Getenv("FGA_STORE_ID"),
        ClientId:     os.Getenv("FGA_CLIENT_ID"),
        ClientSecret: os.Getenv("FGA_CLIENT_SECRET"),
    })

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

    fgaClient := fgaSdk.NewAPIClient(configuration)
}

.NET

// import the SDK
using Auth0.Fga.Api;
using Auth0.Fga.Configuration;
using Environment = System.Environment;

namespace ExampleApp;

class MyProgram {
    static async Task Main() {
        var storeId = Environment.GetEnvironmentVariable("FGA_STORE_ID");
        var environment = Environment.GetEnvironmentVariable("FGA_ENVIRONMENT")
        var configuration = new Configuration(storeId, environment) {
            ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
            ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
        };
        var fgaClient = new Auth0FgaApi(configuration);
    }
}

curl

To obtain the access token:

# Not needed when calling the Playground API
curl -X POST \
   https://fga.us.auth0.com/oauth/token \
   -H 'content-type: application/json' \
   -d '{"client_id":"'$FGA_CLIENT_ID'","client_secret":"'$FGA_CLIENT_SECRET'","audience":"https://api.us1.fga.dev/","grant_type":"client_credentials"}'

# The response will be returned in the form
# {
#  "access_token": "eyJ...Ggg",
#  "expires_in": 86400,
#  "scope": "read:tuples write:tuples check:tuples ... write:authorization-models",
#  "token_type": "Bearer"
# }
# Store this `access_token` value in environment variable `FGA_BEARER_TOKEN`

# For non-playground environment
FGA_API_URL='https://api.us1.fga.dev'
# For playground environment
# FGA_API_URL='https://api.playground.fga.dev'

02. Calling Check API

To check whether user anne has relationship reader with object document:Z

Node.js

// Run a check
const { allowed } = await fgaClient.check({
  tuple_key: {
    user: 'anne',
    relation: 'reader',
    object: 'document:Z',
  },});

// allowed = true

Go

body := fgaSdk.CheckRequestParams{
	TupleKey: &fgaSdk.TupleKey{
		User: fgaSdk.PtrString("anne"),
		Relation: fgaSdk.PtrString("reader"),
		Object: fgaSdk.PtrString("document:Z"),
	},
data, response, err := fgaClient.Auth0FgaApi.Check(context.Background()).Body(body).Execute()

// data = { allowed: true }

.NET

// Run a check
var response = await fgaClient.Check(new CheckRequestParams(new TupleKey {
  User = "anne",
  Relation = "reader",
  Object = "document:Z"
});

// response.Allowed = true

curl

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 '{"tuple_key":{"user":"anne","relation":"reader","object":"document:Z"}}'

# Response: {"allowed":true}

The result's allowed field will return true if the relationship exists and false if the relationship does not exist.

Related Section

Take a look at the following section for more on how to perform authorization checks in your system

Auth0 FGA Check API

Read the Check API documentation and see how it works.

• More