sandcastle-sdk

Auth0 FGA SDK for JavaScript

Stats

StarsIssuesVersionUpdatedCreatedSize
sandcastle-sdk
0.4.05 days ago4 months agoMinified + gzip package size for sandcastle-sdk in KB

Readme

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

This is an autogenerated JS/TS SDK for Auth0 Fine Grained Authorization (FGA). It provides a wrapper around Auth0 FGA's API and includes TS typings.

Table of Contents

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

Installation

Using npm:

npm install sandcastle-sdk

Using yarn:

yarn add sandcastle-sdk

Getting Started

Initializing the API Client

const { Auth0FgaApi } = require('sandcastle-sdk'); // OR import { Auth0FgaApi } from 'sandcastle-sdk';

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 "us1". Provide the store id, client id and client secret you have created on the Dashboard.

PoC

If you are an Auth0 FGA PoC participant, you need to set the AUTH0_FGA_ENVIRONMENT variable to "poc". Provide the store id, client id and client secret you have received from us.

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 /{store_id}/check Check whether a user is authorized to access an object
deleteTokenIssuer DELETE /{store_id}/settings/token-issuers/{id} Remove 3rd party token issuer for Auth0 FGA read and write operation
expand POST /{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 /{store_id}/read Get tuples from the store that matches a query, without following userset rewrite rules
readAssertions GET /{store_id}/assertions/{authorization_model_id} Read assertions for an authorization model ID
readAuthorizationModel GET /{store_id}/authorization-models/{id} Return a particular version of an authorization model
readAuthorizationModels GET /{store_id}/authorization-models Return all the authorization model IDs for a particular store
readSettings GET /{store_id}/settings Return store settings, including the environment tag
write POST /{store_id}/write Add or delete tuples from the store
writeAssertions POST /{store_id}/assertions/{authorization_model_id} Upsert assertions for an authorization model ID
writeAuthorizationModel POST /{store_id}/authorization-models Create a new authorization model
writeSettings PATCH /{store_id}/settings Update the environment tag for a store
writeTokenIssuer POST /{store_id}/settings/token-issuers Add 3rd party token issuer for Auth0 FGA read and write operations

check

Name Type Description Notes
body Auth0FgaCheckRequestParams
Return type

Auth0FgaCheckResponse

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 Auth0FgaExpandRequestParams
Return type

Auth0FgaExpandResponse

read

Name Type Description Notes
body Auth0FgaReadRequestParams
Return type

Auth0FgaReadResponse

readAssertions

Name Type Description Notes
authorizationModelId string The authorization model ID [default to undefined]
Return type

Auth0FgaReadAssertionsResponse

readAuthorizationModel

Name Type Description Notes
id string The authorization model ID [default to undefined]
Return type

Auth0FgaReadAuthorizationModelResponse

readAuthorizationModels

Name Type Description Notes
pageSize number [default to undefined]
Return type

Auth0FgaReadAuthorizationModelsResponse

readSettings

Name Type Description Notes
Return type

SettingsSettings

write

Name Type Description Notes
body Auth0FgaWriteRequestParams
Return type

object

writeAssertions

Name Type Description Notes
authorizationModelId string The authorization model ID [default to undefined]
Return type

object

writeAuthorizationModel

Name Type Description Notes
body AuthorizationmodelTypeDefinitions
Return type

Auth0FgaWriteAuthorizationModelResponse

writeSettings

Name Type Description Notes
body Auth0FgaWriteSettingsRequestParams
Return type

SettingsSettings

writeTokenIssuer

Name Type Description Notes
body Auth0FgaWriteTokenIssuersRequestParams
Return type

SettingsTokenIssuer

Models

Auth0FgaAssertion

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

Auth0FgaCheckRequestParams

Properties
Name Type Description Notes
tuple_key Auth0FgaTupleKey [optional] [default to undefined]
authorization_model_id string [optional] [default to undefined]
trace boolean defaults to false. making it true has performance implications. only use for debugging purposes, etc. [optional] [readonly] [default to undefined]

Auth0FgaCheckResponse

Properties
Name Type Description Notes
allowed boolean [optional] [default to undefined]
resolution string [optional] [default to undefined]

Auth0FgaExpandRequestParams

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

Auth0FgaExpandResponse

Properties
Name Type Description Notes
tree Auth0FgaUsersetTree [optional] [default to undefined]

Auth0FgaReadAssertionsResponse

Properties
Name Type Description Notes
authorization_model_id string The authorization model ID [optional] [default to undefined]
assertions Auth0FgaAssertion[] [optional] [default to undefined]

Auth0FgaReadAuthorizationModelResponse

Properties
Name Type Description Notes
authorization_model AuthorizationmodelAuthorizationModel [optional] [default to undefined]

Auth0FgaReadAuthorizationModelsResponse

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

Auth0FgaReadRequestParams

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

Auth0FgaReadResponse

Properties
Name Type Description Notes
tuples Auth0FgaTuple[] [optional] [default to undefined]

Auth0FgaTuple

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

Auth0FgaTupleKey

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

Auth0FgaTupleKeys

Properties
Name Type Description Notes
tuple_keys Auth0FgaTupleKey[] [default to undefined]

Auth0FgaUsersetTree

Properties
Name Type Description Notes
root UsersetTreeNode [optional] [default to undefined]

Auth0FgaUsersetTreeDifference

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

Auth0FgaUsersetTreeTupleToUserset

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

Auth0FgaWriteAssertionsRequestParams

Properties
Name Type Description Notes
assertions Auth0FgaAssertion[] [default to undefined]

Auth0FgaWriteAuthorizationModelResponse

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

Auth0FgaWriteRequestParams

Properties
Name Type Description Notes
writes Auth0FgaTupleKeys [optional] [default to undefined]
deletes Auth0FgaTupleKeys [optional] [default to undefined]
authorization_model_id string [optional] [default to undefined]
lock_tuple Auth0FgaTuple [optional] [default to undefined]

Auth0FgaWriteSettingsRequestParams

Properties
Name Type Description Notes
environment SettingsEnvironment [optional] [default to undefined]

Auth0FgaWriteTokenIssuersRequestParams

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

AuthorizationmodelAuthorizationModel

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

AuthorizationmodelDifference

Properties
Name Type Description Notes
base AuthorizationmodelUserset [default to undefined]
subtract AuthorizationmodelUserset [default to undefined]

AuthorizationmodelObjectRelation

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

AuthorizationmodelTupleToUserset

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

AuthorizationmodelTypeDefinition

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

AuthorizationmodelTypeDefinitions

Properties
Name Type Description Notes
type_definitions AuthorizationmodelTypeDefinition[] [optional] [default to undefined]

AuthorizationmodelUserset

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 AuthorizationmodelObjectRelation [optional] [default to undefined]
tupleToUserset AuthorizationmodelTupleToUserset [optional] [default to undefined]
union AuthorizationmodelUsersets [optional] [default to undefined]
intersection AuthorizationmodelUsersets [optional] [default to undefined]
difference AuthorizationmodelDifference [optional] [default to undefined]

AuthorizationmodelUsersets

Properties
Name Type Description Notes
child AuthorizationmodelUserset[] [optional] [default to undefined]

ProtobufAny

Properties
Name Type Description Notes
typeUrl string [optional] [default to undefined]
value string [optional] [default to undefined]

RpcStatus

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

SettingsEnvironment

Enum
  • EnvironmentUnspecified (value: 'ENVIRONMENT_UNSPECIFIED')

  • Development (value: 'DEVELOPMENT')

  • Staging (value: 'STAGING')

  • Production (value: 'PRODUCTION')

SettingsSettings

Properties
Name Type Description Notes
environment SettingsEnvironment [optional] [default to undefined]
token_issuers SettingsTokenIssuer[] [optional] [default to undefined]

SettingsTokenIssuer

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

UsersetTreeComputed

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

UsersetTreeLeaf

Properties
Name Type Description Notes
users UsersetTreeUsers [optional] [default to undefined]
computed UsersetTreeComputed [optional] [default to undefined]
tupleToUserset Auth0FgaUsersetTreeTupleToUserset [optional] [default to undefined]

UsersetTreeNode

Properties
Name Type Description Notes
name string [optional] [default to undefined]
leaf UsersetTreeLeaf [optional] [default to undefined]
difference Auth0FgaUsersetTreeDifference [optional] [default to undefined]
union UsersetTreeNodes [optional] [default to undefined]
intersection UsersetTreeNodes [optional] [default to undefined]

UsersetTreeNodes

Properties
Name Type Description Notes
nodes UsersetTreeNode[] [optional] [default to undefined]

UsersetTreeUsers

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

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.

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.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.