sandcastle-sdk

DEPRECATION NOTICE: This SDK has been deprecated in favour of @auth0/fga. Please install it from there.
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](#write-authorization-model)
- [Read a Single Authorization Model](#read-a-single-authorization-model)
- [Read Authorization Model IDs](#read-authorization-model-ids)
- [Check](#check)
- [Write Tuples](#write-tuples)
- [Delete Tuples](#delete-tuples)
- [Expand](#expand)
- [Read](#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.

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

Return type

ReadAssertionsResponse

readAuthorizationModel

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- | | id | string | The authorization model ID | default to undefined|

Return type

ReadAuthorizationModelResponse

readAuthorizationModels

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- | | pageSize | number | | default to undefined|| continuationToken | string | | default to undefined|

Return type

ReadAuthorizationModelsResponse

readSettings

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- |

Return type

Settings

write

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- | | body | WriteRequestParams | | |

Return type

object

writeAssertions

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- | | authorizationModelId | string | The authorization model ID | default to undefined|| body | WriteAssertionsRequestParams | | |

Return type

object

writeAuthorizationModel

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- | | body | TypeDefinitions | | |

Return type

WriteAuthorizationModelResponse

writeSettings

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- | | body | WriteSettingsRequestParams | | |

Return type

Settings

writeTokenIssuer

| Name | Type | Description | Notes | | ------------- | ------------- | ------------- | ------------- | | body | WriteTokenIssuersRequestParams | | |

Return type

TokenIssuer

Models

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

Any

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- type | string | | optional default to undefined

Assertion

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- tuplekey | TupleKey | | default to undefined expectation | boolean | | default to undefined

AuthorizationModel

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- id | string | | optional default to undefined typedefinitions | 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 ------------ | ------------- | ------------- | ------------- tuplekey | TupleKey | | optional default to undefined authorizationmodelid | 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

CheckResponse

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- allowed | boolean | | optional default to undefined resolution | string | | 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 ------------ | ------------- | ------------- | ------------- tuplekey | TupleKey | | optional default to undefined authorizationmodelid | 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 ------------ | ------------- | ------------- | ------------- authorizationmodelid | string | The authorization model ID | optional default to undefined assertions | Assertion | | optional default to undefined

ReadAuthorizationModelResponse

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- authorizationmodel | AuthorizationModel | | optional default to undefined

ReadAuthorizationModelsResponse

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- authorizationmodelids | string | | optional default to undefined continuationtoken | string | | optional default to undefined

ReadRequestParams

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- tuplekey | TupleKey | | optional default to undefined authorizationmodelid | string | | optional default to undefined

ReadResponse

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- tuples | Tuple | | optional default to undefined

ReadTuplesRequestParams

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- pagesize | number | | optional default to undefined continuationtoken | string | | optional default to undefined

ReadTuplesResponse

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- tuples | Tuple | | optional default to undefined continuationtoken | string | | optional default to undefined

Settings

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- environment | Environment | | optional default to undefined tokenissuers | 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 issuerurl | 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 ------------ | ------------- | ------------- | ------------- tuplekeys | TupleKey | | default to undefined

TypeDefinition

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- type | string | | default to undefined relations | Record> | | default to undefined

TypeDefinitions

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- typedefinitions | 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 ------------ | ------------- | ------------- | ------------- authorizationmodelid | string | | optional default to undefined

WriteRequestParams

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- writes | TupleKeys | | optional default to undefined deletes | TupleKeys | | optional default to undefined authorizationmodelid | string | | optional default to undefined locktuple | Tuple | | optional default to undefined

WriteSettingsRequestParams

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- environment | Environment | | optional default to undefined

WriteTokenIssuersRequestParams

Properties

Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- issuerurl | 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.

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.