JavaScript and Node.js SDK for Auth0 Fine Grained Authorization (FGA)

This is an autogenerated JavaScript SDK for Auth0 Fine Grained Authorization (FGA). It provides a wrapper around the Auth0 Fine Grained Authorization API, and includes TS typings.

Warning: This SDK comes with no SLAs and is not production-ready!

Table of Contents

• About Auth0 Fine Grained Authorization
• Resources
• Installation
• Getting Started
  • Initializing the API Client
  • Getting your Store ID, Client ID and Client Secret
  • Calling the API
    • Write Authorization Model
    • Read a Single Authorization Model
    • Read Authorization Model IDs
    • Check
    • Write Tuples
    • Delete Tuples
    • Expand
    • Read
  • API Endpoints
  • Models
• Contributing
  • Issues
  • Pull Requests [Note: We are not accepting Pull Requests at this time!]
• License

About Auth0 Fine Grained Authorization

Auth0 Fine Grained Authorization (FGA) is the early-stage product we are building at Auth0 as part of Auth0Lab to solve fine-grained authorization at scale. If you are interested in learning more about our plans, please reach out via our Discord chat.

Please note:

• At this point in time, Auth0 Fine Grained Authorization does not come with any SLAs; availability and uptime are not guaranteed.
• While this project is in its early stages, the SDK methods are in flux and might change without a major bump

Resources

• The Auth0 FGA Playground
• The Auth0 FGA Documentation
• Zanzibar Academy
• Auth0Lab on Twitter
• Discord Community

Installation

Using npm:

npm install @auth0/fga

Using yarn:

yarn add @auth0/fga

Getting Started

Initializing the API Client

const { Auth0FgaApi } = require('@auth0/fga'); // OR import { Auth0FgaApi } from '@auth0/fga';

const auth0Fga = new Auth0FgaApi({
  environment: AUTH0_FGA_ENVIRONMENT,
  storeId: AUTH0_FGA_STORE_ID,
  clientId: AUTH0_FGA_CLIENT_ID,
  clientSecret: AUTH0_FGA_CLIENT_SECRET,
});

Getting your Store ID, Client ID and Client Secret

Production

Make sure you have created your credentials on the Auth0 FGA Dashboard. Learn how ➡

You will need to set the AUTH0_FGA_ENVIRONMENT variable to "us". Provide the store id, client id and client secret you have created on the Dashboard.

Playground

If you are testing this on the public playground, you need to set your AUTH0_FGA_ENVIRONMENT to "playground".

To get your store id, you may copy it from the store you have created on the Playground. Learn how ➡

In the playground environment, you do not need to provide a client id and client secret.

Calling the API

Write Authorization Model

Note: To learn how to build your authorization model, check the Docs at https://docs.fga.dev/

Note: The Auth0 FGA Playground, Dashboard and Documentation use a friendly syntax which gets translated to the API syntax seen below. Learn more about the Auth0 FGA configuration language.

const { id } = await auth0Fga.writeAuthorizationModel({
  type_definitions: [{
    type: "repo",
    relations: {
      "writer": { "this": {} },
      "reader": {
        "union": {
          "child": [
            { "this": {} },
            { "computedUserset": {
               "object": "",
              "relation": "writer" }
            }
          ]
        }
      }
    } }],
});

// id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"

Read a Single Authorization Model

// Assuming `1uHxCSuTP0VKPYSnkq1pbb1jeZw` is an id of a single model
const { authorization_model: authorizationModel } = await auth0Fga.readAuthorizationModel('1uHxCSuTP0VKPYSnkq1pbb1jeZw');

// authorizationModel = { id: "1uHxCSuTP0VKPYSnkq1pbb1jeZw", type_definitions: [...] }

Read Authorization Model IDs

const { authorization_model_ids: authorizationModelIds } = await auth0Fga.readAuthorizationModels();

// authorizationModelIds = ["1uHxCSuTP0VKPYSnkq1pbb1jeZw", "GtQpMohWezFmIbyXxVEocOCxxgq"];

Check

Provide a tuple and ask the Auth0 FGA API to check for a relationship

const result = await auth0Fga.check({
  tuple_key: {
    user: "81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "admin",
    object: "workspace:675bcac4-ad38-4fb1-a19a-94a5648c91d6",
  },
});

// result = { allowed: true, resolution: "" }

Write Tuples

await auth0Fga.write({
  writes: {
    tuple_keys: [{ user: "anne", relation: "reader", object: "repo:auth0/express-jwt" }],
  },
});

Delete Tuples

await auth0Fga.write({
  deletes: {
    tuple_keys: [{ user: "anne", relation: "reader", object: "repo:auth0/express-jwt" }],
  },
});

Expand

const { tree } = await auth0Fga.expand({
  tuple_key: {
    relation: "admin",
    object: "workspace:675bcac4-ad38-4fb1-a19a-94a5648c91d6",
  },
});

// tree = {...}

Read

// Find if a relationship tuple stating that a certain user is an admin on a certain workspace
const body = {
  tuple_key: {
    user: "81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "admin",
    object: "workspace:675bcac4-ad38-4fb1-a19a-94a5648c91d6",
  },
};

// Find all relationship tuples where a certain user has a relationship as any relation to a certain workspace
const body = {
  tuple_key: {
    user: "81684243-9356-4421-8fbf-a4f8d36aa31b",
    object: "workspace:675bcac4-ad38-4fb1-a19a-94a5648c91d6",
  },
};

// Find all relationship tuples where a certain user is an admin on any workspace
const body = {
  tuple_key: {
    user: "81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "admin",
    object: "workspace:",
  },
};

// Find all relationship tuples where any user has a relationship as any relation with a particular workspace
const body = {
  tuple_key: {
    object: "workspace:675bcac4-ad38-4fb1-a19a-94a5648c91d6",
  },
};

const { tuples } = await auth0Fga.read(body);

// In all the above situations, the response will be of the form:
// tuples = [{ key: { user, relation, object }, timestamp: ... }]

API Endpoints

Method	HTTP request	Description
check	POST /stores/{store_id}/check	Check whether a user is authorized to access an object
deleteTokenIssuer	DELETE /stores/{store_id}/settings/token-issuers/{id}	Remove 3rd party token issuer for Auth0 FGA read and write operation
expand	POST /stores/{store_id}/expand	Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship
read	POST /stores/{store_id}/read	Get tuples from the store that matches a query, without following userset rewrite rules
readAssertions	GET /stores/{store_id}/assertions/{authorization_model_id}	Read assertions for an authorization model ID
readAuthorizationModel	GET /stores/{store_id}/authorization-models/{id}	Return a particular version of an authorization model
readAuthorizationModels	GET /stores/{store_id}/authorization-models	Return all the authorization model IDs for a particular store
readSettings	GET /stores/{store_id}/settings	Return store settings, including the environment tag
write	POST /stores/{store_id}/write	Add or delete tuples from the store
writeAssertions	PUT /stores/{store_id}/assertions/{authorization_model_id}	Upsert assertions for an authorization model ID
writeAuthorizationModel	POST /stores/{store_id}/authorization-models	Create a new authorization model
writeSettings	PATCH /stores/{store_id}/settings	Update the environment tag for a store
writeTokenIssuer	POST /stores/{store_id}/settings/token-issuers	Add 3rd party token issuer for Auth0 FGA read and write operations

check

Name	Type	Description	Notes
body	CheckRequestParams

Return type

CheckResponse

deleteTokenIssuer

Name	Type	Description	Notes
id	string	Id of token issuer to be removed	[default to undefined]

Return type

object

expand

Name	Type	Description	Notes
body	ExpandRequestParams

Return type

ExpandResponse

read

Name	Type	Description	Notes
body	ReadRequestParams

Return type

ReadResponse

readAssertions

Name	Type	Description	Notes
authorizationModelId	string		[default to undefined]

Return type

ReadAssertionsResponse

readAuthorizationModel

Name	Type	Description	Notes
id	string		[default to undefined]

Return type

ReadAuthorizationModelResponse

readAuthorizationModels

Name	Type	Description	Notes
pageSize	number		[default to undefined]

Return type

ReadAuthorizationModelsResponse

readSettings

Name	Type	Description	Notes

Return type

ReadSettingsResponse

write

Name	Type	Description	Notes
body	WriteRequestParams

Return type

object

writeAssertions

Name	Type	Description	Notes
authorizationModelId	string		[default to undefined]

Return type

object

writeAuthorizationModel

Name	Type	Description	Notes
body	TypeDefinitions

Return type

WriteAuthorizationModelResponse

writeSettings

Name	Type	Description	Notes
body	WriteSettingsRequestParams

Return type

WriteSettingsResponse

writeTokenIssuer

Name	Type	Description	Notes
body	WriteTokenIssuersRequestParams

Return type

WriteTokenIssuersResponse

Models

• Any
• Assertion
• AuthorizationModel
• AuthorizationmodelDifference
• AuthorizationmodelTupleToUserset
• CheckRequestParams
• CheckResponse
• Computed
• Environment
• ExpandRequestParams
• ExpandResponse
• Leaf
• Node
• Nodes
• ObjectRelation
• ReadAssertionsResponse
• ReadAuthorizationModelResponse
• ReadAuthorizationModelsResponse
• ReadRequestParams
• ReadResponse
• ReadSettingsResponse
• Status
• TokenIssuer
• Tuple
• TupleKey
• TupleKeys
• TypeDefinition
• TypeDefinitions
• Users
• Userset
• UsersetTree
• UsersetTreeDifference
• UsersetTreeTupleToUserset
• Usersets
• WriteAssertionsRequestParams
• WriteAuthorizationModelResponse
• WriteRequestParams
• WriteSettingsRequestParams
• WriteSettingsResponse
• WriteTokenIssuersRequestParams
• WriteTokenIssuersResponse

Any

Properties

Name	Type	Description	Notes
type	string		[optional] [default to undefined]

Assertion

Properties

Name	Type	Description	Notes
tuple_key	TupleKey		[default to undefined]
expectation	boolean		[default to undefined]

AuthorizationModel

Properties

Name	Type	Description	Notes
id	string		[optional] [default to undefined]
type_definitions	TypeDefinition[]		[optional] [default to undefined]

AuthorizationmodelDifference

Properties

Name	Type	Description	Notes
base	Userset		[default to undefined]
subtract	Userset		[default to undefined]

AuthorizationmodelTupleToUserset

Properties

Name	Type	Description	Notes
tupleset	ObjectRelation		[optional] [default to undefined]
computedUserset	ObjectRelation		[optional] [default to undefined]

CheckRequestParams

Properties

Name	Type	Description	Notes
tuple_key	TupleKey		[optional] [default to undefined]
authorization_model_id	string		[optional] [default to undefined]
trace	boolean	Defaults to false. Making it true has performance implications.	[optional] [readonly] [default to undefined]

CheckResponse

Properties

Name	Type	Description	Notes
allowed	boolean		[optional] [default to undefined]
resolution	string	For internal use only.	[optional] [default to undefined]

Computed

Properties

Name	Type	Description	Notes
userset	string		[optional] [default to undefined]

Environment

Enum

• EnvironmentUnspecified (value: 'ENVIRONMENT_UNSPECIFIED')

• Development (value: 'DEVELOPMENT')

• Staging (value: 'STAGING')

• Production (value: 'PRODUCTION')

ExpandRequestParams

Properties

Name	Type	Description	Notes
tuple_key	TupleKey		[optional] [default to undefined]
authorization_model_id	string		[optional] [default to undefined]

ExpandResponse

Properties

Name	Type	Description	Notes
tree	UsersetTree		[optional] [default to undefined]

Leaf

Properties

Name	Type	Description	Notes
users	Users		[optional] [default to undefined]
computed	Computed		[optional] [default to undefined]
tupleToUserset	UsersetTreeTupleToUserset		[optional] [default to undefined]

Node

Properties

Name	Type	Description	Notes
name	string		[optional] [default to undefined]
leaf	Leaf		[optional] [default to undefined]
difference	UsersetTreeDifference		[optional] [default to undefined]
union	Nodes		[optional] [default to undefined]
intersection	Nodes		[optional] [default to undefined]

Nodes

Properties

Name	Type	Description	Notes
nodes	Node[]		[optional] [default to undefined]

ObjectRelation

Properties

Name	Type	Description	Notes
object	string		[optional] [default to undefined]
relation	string		[optional] [default to undefined]

ReadAssertionsResponse

Properties

Name	Type	Description	Notes
authorization_model_id	string		[optional] [default to undefined]
assertions	Assertion[]		[optional] [default to undefined]

ReadAuthorizationModelResponse

Properties

Name	Type	Description	Notes
authorization_model	AuthorizationModel		[optional] [default to undefined]

ReadAuthorizationModelsResponse

Properties

Name	Type	Description	Notes
authorization_model_ids	string		[optional] [default to undefined]
continuation_token	string		[optional] [default to undefined]

ReadRequestParams

Properties

Name	Type	Description	Notes
tuple_key	TupleKey		[optional] [default to undefined]
authorization_model_id	string		[optional] [default to undefined]
page_size	number		[optional] [default to undefined]
continuation_token	string		[optional] [default to undefined]

ReadResponse

Properties

Name	Type	Description	Notes
tuples	Tuple[]		[optional] [default to undefined]
continuation_token	string		[optional] [default to undefined]

ReadSettingsResponse

Properties

Name	Type	Description	Notes
environment	Environment		[optional] [default to undefined]
token_issuers	TokenIssuer[]		[optional] [default to undefined]

Status

Properties

Name	Type	Description	Notes
code	number		[optional] [default to undefined]
message	string		[optional] [default to undefined]
details	Any[]		[optional] [default to undefined]

TokenIssuer

Properties

Name	Type	Description	Notes
id	string		[optional] [default to undefined]
issuer_url	string		[optional] [default to undefined]

Tuple

Properties

Name	Type	Description	Notes
key	TupleKey		[optional] [default to undefined]
timestamp	string		[optional] [default to undefined]

TupleKey

Properties

Name	Type	Description	Notes
object	string		[optional] [default to undefined]
relation	string		[optional] [default to undefined]
user	string		[optional] [default to undefined]

TupleKeys

Properties

Name	Type	Description	Notes
tuple_keys	TupleKey[]		[default to undefined]

TypeDefinition

Properties

Name	Type	Description	Notes
type	string		[default to undefined]
relations	Record<string, Userset>		[default to undefined]

TypeDefinitions

Properties

Name	Type	Description	Notes
type_definitions	TypeDefinition[]		[optional] [default to undefined]

Users

Properties

Name	Type	Description	Notes
users	string		[optional] [default to undefined]

Userset

Properties

Name	Type	Description	Notes
_this	object	A DirectUserset is a sentinel message for referencing the direct members specified by an object/relation mapping.	[optional] [default to undefined]
computedUserset	ObjectRelation		[optional] [default to undefined]
tupleToUserset	AuthorizationmodelTupleToUserset		[optional] [default to undefined]
union	Usersets		[optional] [default to undefined]
intersection	Usersets		[optional] [default to undefined]
difference	AuthorizationmodelDifference		[optional] [default to undefined]

UsersetTree

Properties

Name	Type	Description	Notes
root	Node		[optional] [default to undefined]

UsersetTreeDifference

Properties

Name	Type	Description	Notes
base	Node		[optional] [default to undefined]
subtract	Node		[optional] [default to undefined]

UsersetTreeTupleToUserset

Properties

Name	Type	Description	Notes
tupleset	string		[optional] [default to undefined]
computed	Computed[]		[optional] [default to undefined]

Usersets

Properties

Name	Type	Description	Notes
child	Userset[]		[optional] [default to undefined]

WriteAssertionsRequestParams

Properties

Name	Type	Description	Notes
assertions	Assertion[]		[default to undefined]

WriteAuthorizationModelResponse

Properties

Name	Type	Description	Notes
authorization_model_id	string		[optional] [default to undefined]

WriteRequestParams

Properties

Name	Type	Description	Notes
writes	TupleKeys		[optional] [default to undefined]
deletes	TupleKeys		[optional] [default to undefined]
authorization_model_id	string		[optional] [default to undefined]
lock_tuple	Tuple		[optional] [default to undefined]

WriteSettingsRequestParams

Properties

Name	Type	Description	Notes
environment	Environment		[optional] [default to undefined]

WriteSettingsResponse

Properties

Name	Type	Description	Notes
environment	Environment		[optional] [default to undefined]
token_issuers	TokenIssuer[]		[optional] [default to undefined]

WriteTokenIssuersRequestParams

Properties

Name	Type	Description	Notes
issuer_url	string		[optional] [default to undefined]

WriteTokenIssuersResponse

Properties

Name	Type	Description	Notes
id	string		[optional] [default to undefined]

Contributing

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

For auth0 related questions/support please use the Support Center.

Pull Requests

Pull Requests are not currently open, please raise an issue or contact a team member on https://discord.gg/8naAwJfWN6 if there is a feature you'd like us to implement.

Author

Auth0Lab

License

This project is licensed under the MIT license. See the LICENSE file for more info.

The code in this repo was auto generated by OpenAPI Generator from a template based on the typescript-axios template and go template, licensed under the Apache License 2.0.