❤
npm
Sign UpSign In

@openfga/sdk
TypeScript icon, indicating that this package has built-in type declarations

0.3.5 • Public • Published

JavaScript and Node.js SDK for OpenFGA

npm Release License FOSSA Status Join our community Twitter

This is an autogenerated JavaScript SDK for OpenFGA. It provides a wrapper around the OpenFGA API definition, and includes TS typings.

Table of Contents

About

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0 based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.

OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.

Resources

Installation

Using npm:

npm install @openfga/sdk

Using yarn:

yarn add @openfga/sdk

Getting Started

Initializing the API Client

Learn how to initialize your SDK

We strongly recommend you initialize the OpenFgaClient only once and then re-use it throughout your app, otherwise you will incur the cost of having to re-initialize multiple times or at every request, the cost of reduced connection pooling and re-use, and would be particularly costly in the client credentials flow, as that flow will be preformed on every request.

The OpenFgaClient will by default retry API requests up to 15 times on 429 and 5xx errors.

No Credentials

const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL, // required
  storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID, // Optional, can be overridden per request
});

API Token

const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL, // required
  storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID, // Optional, can be overridden per request
  credentials: {
    method: CredentialsMethod.ApiToken,
    config: {
      token: process.env.FGA_API_TOKEN, // will be passed as the "Authorization: Bearer ${ApiToken}" request header
    }
  }
});

Client Credentials

const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL, // required
  storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID, // Optional, can be overridden per request
  credentials: {
    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,
    }
  }
});

Get your Store ID

You need your store id to call the OpenFGA API (unless it is to call the CreateStore or ListStores methods).

If your server is configured with authentication enabled, you also need to have your credentials ready.

Calling the API

Note regarding casing in the OpenFgaClient: All input parameters are in camelCase, all response parameters will match the API and are in snake_case.

Note: The Client interface might see several changes over the next few months as we get more feedback before it stabilizes.

Stores

List Stores

Get a paginated list of stores.

API Documentation

const options = { pageSize: 10, continuationToken: "..." };

const { stores } = await fgaClient.listStores(options);

// stores = [{ "id": "01FQH7V8BEG3GPQW93KTRFR8JB", "name": "FGA Demo Store", "created_at": "2022-01-01T00:00:00.000Z", "updated_at": "2022-01-01T00:00:00.000Z" }]
Create Store

Initialize a store.

API Documentation

const { id: storeId } = await fgaClient.createStore({
  name: "FGA Demo Store",
});

// storeId = "01FQH7V8BEG3GPQW93KTRFR8JB"
Get Store

Get information about the current store.

API Documentation

const store = await fgaClient.getStore();

// store = { "id": "01FQH7V8BEG3GPQW93KTRFR8JB", "name": "FGA Demo Store", "created_at": "2022-01-01T00:00:00.000Z", "updated_at": "2022-01-01T00:00:00.000Z" }
Delete Store

Delete a store.

API Documentation

await fgaClient.deleteStore();

Authorization Models

Read Authorization Models

Read all authorization models in the store.

API Documentation

Requires a client initialized with a storeId

const options = { pageSize: 10, continuationToken: "..." };

const { authorization_models: authorizationModels } = await fgaClient.readAuthorizationModels(options);

/*
authorizationModels = [
 { id: "01GXSA8YR785C4FYS3C0RTG7B1", schema_version: "1.1", type_definitions: [...] },
 { id: "01GXSBM5PVYHCJNRNKXMB4QZTW", schema_version: "1.1", type_definitions: [...] }];
*/
Write Authorization Model

Create a new authorization model.

API Documentation

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

Learn more about the OpenFGA configuration language.

You can use the OpenFGA Syntax Transformer to convert between the friendly DSL and the JSON authorization model.

const { authorization_model_id: id } = await fgaClient.writeAuthorizationModel({
  schema_version: "1.1",
  type_definitions: [{
      type: "user",
    }, {
    type: "document",
    relations: {
      "writer": { "this": {} },
      "viewer": {
        "union": {
          "child": [
            { "this": {} },
            { "computedUserset": {
               "object": "",
              "relation": "writer" }
            }
          ]
        }
      }
    } }],
});

// id = "01GXSA8YR785C4FYS3C0RTG7B1"
Read a Single Authorization Model

Read a particular authorization model.

const options = {};

// To override the authorization model id for this request
options.authorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1";

const { authorization_model: authorizationModel } = await fgaClient.readAuthorizationModel(options);

// authorizationModel = { id: "01GXSA8YR785C4FYS3C0RTG7B1", schema_version: "1.1", type_definitions: [...] }
Read the Latest Authorization Model

Reads the latest authorization model (note: this ignores the model id in configuration).

API Documentation

const { authorization_model: authorizationModel } = await fgaClient.readLatestAuthorizationModel();

// authorizationModel = { id: "01GXSA8YR785C4FYS3C0RTG7B1", schema_version: "1.1", type_definitions: [...] }

Relationship Tuples

Read Relationship Tuple Changes (Watch)

Reads the list of historical relationship tuple writes and deletes.

API Documentation

const type = 'document';
const options = {
  pageSize: 25,
  continuationToken: 'eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==',
};

const response = await fgaClient.readChanges({ type }, options);

// response.continuation_token = ...
// response.changes = [
//   { tuple_key: { user, relation, object }, operation: "writer", timestamp: ... },
//   { tuple_key: { user, relation, object }, operation: "viewer", timestamp: ... }
// ]
Read Relationship Tuples

Reads the relationship tuples stored in the database. It does not evaluate nor exclude invalid tuples according to the authorization model.

API Documentation

// Find if a relationship tuple stating that a certain user is a viewer of a certain document
const body = {
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  object: "document:roadmap",
};

// Find all relationship tuples where a certain user has any relation to a certain document
const body = {
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  object: "document:roadmap",
};

// Find all relationship tuples where a certain user is a viewer of any document
const body = {
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  object: "document:",
};

// Find all relationship tuples where a certain user has any relation with any document
const body = {
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  object: "document:",
};

// Find all relationship tuples where any user has any relation with a particular document
const body = {
  object: "document:roadmap",
};

// Read all stored relationship tuples
const body = {};

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

// In all the above situations, the response will be of the form:
// tuples = [{ key: { user, relation, object }, timestamp: ... }]
Write (Create and Delete) Relationship Tuples

Create and/or delete relationship tuples to update the system state.

API Documentation

Transaction mode (default)

By default, write runs in a transaction mode where any invalid operation (deleting a non-existing tuple, creating an existing tuple, one of the tuples was invalid) or a server error will fail the entire operation.

const options = {};

// To override the authorization model id for this request
options.authorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1";

await fgaClient.write({
  writes: [{ user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "viewer", object: "document:roadmap" }],
  deletes: [{ user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "editor", object: "document:roadmap" }],
}, options);

// Convenience functions are available
await fgaClient.writeTuples([{ user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "viewer", object: "document:roadmap" }], options);
await fgaClient.deleteTuples([{ user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "editor", object: "document:roadmap" }], options);

// if any error is encountered in the transaction mode, an error will be thrown
Non-transaction mode

The SDK will split the writes into separate requests and send them in parallel chunks (default = 1 item per chunk, each chunk is a transaction).

// if you'd like to disable the transaction mode for writes (requests will be sent in parallel writes)
options.transaction = {
  disable: true,
  maxPerChunk: 1, // defaults to 1 - each chunk is a transaction (even in non-transaction mode)
  maxParallelRequests: 10, // max requests to issue in parallel
};

const response = await fgaClient.write({
  writes: [{ user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "viewer", object: "document:roadmap" }],
  deletes: [{ user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "editor", object: "document:roadmap" }],
}, options);

/*
response = {
  writes: [{ tuple_key: { user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "viewer", object: "document:roadmap", status: "success" } }],
  deletes: [{ tuple_key: { user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation: "editor", object: "document:roadmap", status: "failure", err: <FgaError ...>  } }],
};
*/

Relationship Queries

Check

Check if a user has a particular relation with an object.

API Documentation

const options = {
  // if you'd like to override the authorization model id for this request
  authorizationModelId: "01GXSA8YR785C4FYS3C0RTG7B1",
};

const result = await fgaClient.check({
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  object: "document:roadmap",
}, options);

// result = { allowed: true }
Batch Check

Run a set of checks. Batch Check will return allowed: false if it encounters an error, and will return the error in the body. If 429s or 5xxs are encountered, the underlying check will retry up to 15 times before giving up.

const options = {
  // if you'd like to override the authorization model id for this request
  authorizationModelId: "01GXSA8YR785C4FYS3C0RTG7B1",
}
const { responses } = await fgaClient.batchCheck([{
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  object: "document:budget",
}, {
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "member",
  object: "document:budget",
}, {
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  object: "document:roadmap",
  contextual_tuples: [{
    user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "writer",
    object: "document:roadmap"
  }],
}], options);

/*
responses = [{
  allowed: false,
  _request: {
    user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "viewer",
    object: "document:budget",
  }
}, {
  allowed: false,
  _request: {
    user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "member",
    object: "document:budget",
  },
  err: <FgaError ...>
}, {
  allowed: true,
  _request: {
    user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "viewer",
    object: "document:roadmap",
    contextual_tuples: [{
      user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
      relation: "writer",
      object: "document:roadmap"
    }],
  }},
]
*/

Expand

Expands the relationships in userset tree format.

API Documentation

const options = {};

// To override the authorization model id for this request
options.authorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1";

const { tree } = await fgaClient.expand({
  relation: "viewer",
  object: "document:roadmap",
}, options);

// tree  = { root: { name: "document:roadmap#viewer", leaf: { users: { users: ["user:81684243-9356-4421-8fbf-a4f8d36aa31b", "user:f52a4f7a-054d-47ff-bb6e-3ac81269988f"] } } } }
List Objects

List the objects of a particular type that the user has a certain relation to.

API Documentation

const options = {};

// To override the authorization model id for this request
options.authorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1";

const response = await fgaClient.listObjects({
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  type: "document",
  contextual_tuples: [{
    user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "writer",
    object: "document:budget"
  }],
}, options);

// response.objects = ["document:roadmap"]
List Relations

List the relations a user has with an object. This wraps around BatchCheck to allow checking multiple relationships at once.

Note: Any error encountered when checking any relation will be treated as allowed: false;

const options = {};

// To override the authorization model id for this request
options.authorization_model_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw";

const response = await fgaClient.listRelations({
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  object: "document:roadmap",
  relations: ["can_view", "can_edit", "can_delete"],
  contextual_tuples: [{
    user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
    relation: "writer",
    object: "document:roadmap"
  }],
}, options);

// response.relations = ["can_view", "can_edit"]

Assertions

Read Assertions

Read assertions for a particular authorization model.

API Documentation

const options = {};

// To override the authorization model id for this request
options.authorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1";

const response = await fgaClient.readAssertions(options);

/*
response.assertions = [{
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  object: "document:roadmap",
  expectation: true,
}];
*/
Write Assertions

Update the assertions for a particular authorization model.

API Documentation

const options = {};

// To override the authorization model id for this request
options.authorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1";

const response = await fgaClient.writeAssertions([{
  user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
  relation: "viewer",
  object: "document:roadmap",
  expectation: true,
}], options);

API Endpoints

Method HTTP request Description
ListStores GET /stores List all stores
CreateStore POST /stores Create a store
GetStore GET /stores/{store_id} Get a store
DeleteStore DELETE /stores/{store_id} Delete a store
ReadAuthorizationModels GET /stores/{store_id}/authorization-models Return all the authorization models for a particular store
WriteAuthorizationModel POST /stores/{store_id}/authorization-models Create a new authorization model
ReadAuthorizationModel GET /stores/{store_id}/authorization-models/{id} Return a particular version of an authorization model
ReadChanges GET /stores/{store_id}/changes Return a list of all the tuple changes
Read POST /stores/{store_id}/read Get tuples from the store that matches a query, without following userset rewrite rules
Write POST /stores/{store_id}/write Add or delete tuples from the store
Check POST /stores/{store_id}/check Check whether a user is authorized to access an object
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
ListObjects POST /stores/{store_id}/list-objects [EXPERIMENTAL] Get all objects of the given type that the user has a relation with
ReadAssertions GET /stores/{store_id}/assertions/{authorization_model_id} Read assertions for an authorization model ID
WriteAssertions PUT /stores/{store_id}/assertions/{authorization_model_id} Upsert assertions for an authorization model ID

Models

Models

Contributing

Issues

If you have found a bug or if you have a feature request, please report them on the sdk-generator repo issues section. Please do not report security vulnerabilities on the public GitHub issue tracker.

Pull Requests

All changes made to this repo will be overwritten on the next generation, so we kindly ask that you send all pull requests related to the SDKs to the sdk-generator repo instead.

Author

OpenFGA

License

This project is licensed under the Apache-2.0 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.

Readme

Keywords

Package Sidebar

Install

npm i @openfga/sdk

Repository

github.com/openfga/js-sdk

Homepage

github.com/openfga/js-sdk#readme

Weekly Downloads

18,351

Version

0.3.5

License

Apache-2.0

Unpacked Size

1.34 MB

Total Files

41

Last publish

Collaborators

  • rhamzeh_auth0
  • aaguiarz
Try on RunKit
Report malware