Node.js Library

Installation#

Authzed ships a client library for Node.js at https://github.com/authzed/authzed-node, which can be installed via npm install or yarn add:

yarn#

yarn add https://github.com/authzed/authzed-node

npm#

npm install git+https://github.com/authzed/authzed-node

Creating a client#

The entrypoint in the Authzed Node.js client library is a Client, which must be instantiated with your authentication token:

const authzed = require('authzed-node');
const token = "t_your_token_here_1234567deadbeef";
const client = new authzed.Client(token);

Checking#

To Check, the client provides the check call.

Checking Example#

Let's say we wanted to check if a user has viewer permission on a document.

To do so via the Node.js client, we would first construct the objects we are referencing (here, the document and the user):

const documentNamespace = "mytenant/document"
const userNamespace = "mytenant/user"
const someDocumentViewer = new authzed.ObjectAndRelation();
someDocumentViewer.setNamespace(documentNamespace);
someDocumentViewer.setObjectId("someDocument");
someDocumentViewer.setRelation("viewer");
const someUserReference = new authzed.ObjectAndRelation();
someUserReference.setNamespace(userNamespace);
someUserReference.setObjectId("someuser");
someUserReference.setRelation("...");
const someUser = new authzed.User();
someUser.setUserset(someUserReference);

Next, we issue the check call:

const documentNamespace = "mytenant/document"
const userNamespace = "mytenant/user"
// Build the viewer reference and the user reference.
const someDocumentViewer = new authzed.ObjectAndRelation();
someDocumentViewer.setNamespace(documentNamespace);
someDocumentViewer.setObjectId("someDocument");
someDocumentViewer.setRelation("viewer");
const someUserReference = new authzed.ObjectAndRelation();
someUserReference.setNamespace(userNamespace);
someUserReference.setObjectId("someuser");
someUserReference.setRelation("...");
const someUser = new authzed.User();
someUser.setUserset(someUserReference);
// Build the check request.
const request = new authzed.CheckRequest();
request.setTestUserset(someDocumentViewer);
request.setUser(someUser);
// Make the check request.
client.acl.check(request, function(err, response) {
console.log('User can view the document', response.getIsMember());
});

Writing#

To Write, the client provides the WriteRequest call.

Writing Example#

Let's say we wanted to write some permissions for users on some documents:

mytenant/document:somedocument#viewer@mytenant/user:someuser#...
mytenant/document:somedocument#writer@mytenant/user:anotheruser#...

To do so via the Node.js client, we would first construct the objects we are referencing (here, the document and the users):

const someDocumentViewer = new authzed.ObjectAndRelation();
someDocumentViewer.setNamespace(documentNamespace);
someDocumentViewer.setObjectId("someDocument");
someDocumentViewer.setRelation("viewer");
const someDocumentWriter = new authzed.ObjectAndRelation();
someDocumentWriter.setNamespace(documentNamespace);
someDocumentWriter.setObjectId("someDocument");
someDocumentWriter.setRelation("writer");
const someUserReference = new authzed.ObjectAndRelation();
someUserReference.setNamespace(userNamespace);
someUserReference.setObjectId("someuser");
someUserReference.setRelation("...");
const someUser = new authzed.User();
someUser.setUserset(someUserReference);
const anotherUserReference = new authzed.ObjectAndRelation();
anotherUserReference.setNamespace(userNamespace);
anotherUserReference.setObjectId("anotheruser");
anotherUserReference.setRelation("...");
const anotherUser = new authzed.User();
anotherUser.setUserset(anotherUserReference);

Next, we can call WriteRequest to write the permission tuples:

// Construct the references.
const someDocumentViewer = new authzed.ObjectAndRelation();
someDocumentViewer.setNamespace(documentNamespace);
someDocumentViewer.setObjectId("someDocument");
someDocumentViewer.setRelation("viewer");
const someDocumentWriter = new authzed.ObjectAndRelation();
someDocumentWriter.setNamespace(documentNamespace);
someDocumentWriter.setObjectId("someDocument");
someDocumentWriter.setRelation("writer");
const someUserReference = new authzed.ObjectAndRelation();
someUserReference.setNamespace(userNamespace);
someUserReference.setObjectId("someuser");
someUserReference.setRelation("...");
const anotherUserReference = new authzed.ObjectAndRelation();
anotherUserReference.setNamespace(userNamespace);
anotherUserReference.setObjectId("anotheruser");
anotherUserReference.setRelation("...");
// Build the write request.
const viewerTuple = new authzed.RelationTuple();
viewerTuple.setObjectAndRelation(someDocumentViewer);
viewerTuple.setUser(someUser);
const writerTuple = new authzed.RelationTuple();
writerTuple.setObjectAndRelation(someDocumentWriter);
writerTuple.setUser(anotherUserReference);
const viewUpdate = new authzed.RelationTupleUpdate();
viewUpdate.setOperation(authzed.Operation.CREATE);
viewUpdate.setRelationTuple(viewerTuple);
const writeUpdate = new authzed.RelationTupleUpdate();
writeUpdate.setOperation(authzed.Operation.CREATE);
writeUpdate.setRelationTuple(writerTuple);
const request = new authzed.WriteRequest();
request.addUpdates(viewUpdate);
request.addUpdates(writeUpdate);
// Make the write request.
client.acl.write(request, function(err, response) {
// Save the Zookie somewhere.
some_document.setRevision(response.getRevision());
});

Full Example#

A full example can be found at https://github.com/authzed/authzed-node/blob/main/README.md