@openfga/sdk
Advanced tools
This is an autogenerated JavaScript SDK for OpenFGA. It provides a wrapper around the OpenFGA API definition, and includes TS typings.
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.
Using npm:
npm install @openfga/sdk
Using yarn:
yarn add @openfga/sdk
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
OpenFgaClientwill by default retry API requests up to 15 times on 429 and 5xx errors.
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_MODEL_ID, // Optional, can be overridden per request
});
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_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
}
}
});
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_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,
}
}
});
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.
Note regarding casing in the OpenFgaClient: All input parameters are in
camelCase, all response parameters will match the API and are insnake_case.
Note: The Client interface might see several changes over the next few months as we get more feedback before it stabilizes.
Get a paginated list of stores.
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" }]
Initialize a store.
const { id: storeId } = await fgaClient.createStore({
name: "FGA Demo Store",
});
// storeId = "01FQH7V8BEG3GPQW93KTRFR8JB"
Get information about the current store.
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 a store.
await fgaClient.deleteStore();
Read all authorization models in the store.
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: [...] }];
*/
Create a new authorization model.
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 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: [...] }
Reads the latest authorization model (note: this ignores the model id in configuration).
const { authorization_model: authorizationModel } = await fgaClient.readLatestAuthorizationModel();
// authorizationModel = { id: "01GXSA8YR785C4FYS3C0RTG7B1", schema_version: "1.1", type_definitions: [...] }
Reads the list of historical relationship tuple writes and deletes.
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: ... }
// ]
Reads the relationship tuples stored in the database. It does not evaluate nor exclude invalid tuples according to the authorization model.
// 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: ... }]
Create and/or delete relationship tuples to update the system state.
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
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 ...> } }],
};
*/
Check if a user has a particular relation with an object.
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 }
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",
contextualTuples: [{
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",
contextualTuples: [{
user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
relation: "writer",
object: "document:roadmap"
}],
}},
]
*/
Expands the relationships in userset tree format.
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 the objects of a particular type that the user has a certain relation to.
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",
contextualTuples: [{
user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
relation: "writer",
object: "document:budget"
}],
}, options);
// response.objects = ["document:roadmap"]
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"],
contextualTuples: [{
user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
relation: "writer",
object: "document:roadmap"
}],
}, options);
// response.relations = ["can_view", "can_edit"]
List the users who have a certain relation to a particular type.
const options = {};
// To override the authorization model id for this request
options.authorization_model_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw";
// Only a single filter is allowed for the time being
const userFilters = [{type: "user"}];
// user filters can also be of the form
// const userFilters = [{type: "team", relation: "member"}];
const response = await fgaClient.listUsers({
object: {
type: "document",
id: "roadmap"
},
relation: "can_read",
user_filters: userFilters,
context: {
"view_count": 100
},
contextualTuples:
[{
user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
relation: "editor",
object: "folder:product"
}, {
user: "folder:product",
relation: "parent",
object: "document:roadmap"
}]
}, options);
// response.users = [{object: {type: "user", id: "81684243-9356-4421-8fbf-a4f8d36aa31b"}}, {userset: { type: "user" }}, ...]
Read assertions for a particular authorization model.
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,
}];
*/
Update the assertions for a particular authorization model.
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);
If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 15 times with a minimum wait time of 100 milliseconds between each attempt.
To customize this behavior, create an object with maxRetry and minWaitInMs properties. maxRetry determines the maximum number of retries (up to 15), while minWaitInMs sets the minimum wait time between retries in milliseconds.
Apply your custom retry values by setting to retryParams on the to the configuration object passed to the OpenFgaClient call.
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_MODEL_ID, // Optional, can be overridden per request
retryParams: {
maxRetry: 3, // retry up to 3 times on API requests
minWaitInMs: 250 // wait a minimum of 250 milliseconds between requests
}
});
| 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 |
This SDK supports producing metrics that can be consumed as part of an OpenTelemetry setup. For more information, please see the documentation
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.
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.
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.
FAQs
JavaScript and Node.js SDK for OpenFGA
The npm package @openfga/sdk receives a total of 25,425 weekly downloads. As such, @openfga/sdk popularity was classified as popular.
We found that @openfga/sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.