JavaScript and Node.js SDK for Auth0 Fine Grained Authorization (FGA)
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
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:
Using yarn:
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 /{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
Return type
CheckResponse
deleteTokenIssuer
Name |
Type |
Description |
Notes |
id |
string |
Id of token issuer to be removed |
[default to undefined] |
Return type
object
expand
Return type
ExpandResponse
read
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] |
Return type
ReadAuthorizationModelsResponse
readSettings
Name |
Type |
Description |
Notes |
Return type
Settings
write
Return type
object
writeAssertions
Name |
Type |
Description |
Notes |
authorizationModelId |
string |
The authorization model ID |
[default to undefined] |
Return type
object
writeAuthorizationModel
Return type
WriteAuthorizationModelResponse
writeSettings
Return type
Settings
writeTokenIssuer
Return type
TokenIssuer
Models
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. 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 |
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 |
The authorization model ID |
[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] |
ReadResponse
Properties
Name |
Type |
Description |
Notes |
tuples |
Tuple[] |
|
[optional] [default to undefined] |
ReadTuplesRequestParams
Properties
Name |
Type |
Description |
Notes |
page_size |
number |
|
[optional] [default to undefined] |
continuation_token |
string |
|
[optional] [default to undefined] |
ReadTuplesResponse
Properties
Name |
Type |
Description |
Notes |
tuples |
Tuple[] |
|
[optional] [default to undefined] |
continuation_token |
string |
|
[optional] [default to undefined] |
Settings
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] |
WriteTokenIssuersRequestParams
Properties
Name |
Type |
Description |
Notes |
issuer_url |
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.