Skip to main content
Version: 2.0.0

Node.js SDK Quickstart

Working with the Permit.io Node.js SDK enables developers to seamlessly integrate robust authorization management into their applications. This SDK simplifies the implementation of fine-grained access controls, whether you're managing user roles with RBAC, policies with ABAC, relationships with ReBAC, or making use of other powerful Permit features like Elements.

Prerequisites:

This tutorial is for users who have already set up at least one policy in Permit.io. If you haven't done so yet, please refer to this guide first.

Adding the Permit.io Node SDK to your project​

1. Install the Permit.io SDK​

To start, you need to install the Permit.io SDK in your project. Open your terminal and run the following command:

npm install permitio

This will add the Permit.io SDK to your project, allowing you to integrate authorization management seamlessly.

2. Import the SDK into your code​

After installing the SDK, you need to import it into your application.

import { Permit } from "permitio";

3. Create a new Instance of the SDK​

Next, create a new Permit object instance of the Permit SDK. You'll need a secret API key, which you can obtain by following the instructions provided in the setup section of the Permit.io documentation.

// This first line initializes the SDK and connects your Node.js app
// to the Permit.io PDP container you've set up in the previous step.
const permit = new Permit({
  // your API Key
  token: "[YOUR_API_KEY]",

  // in production, you might need to change this url to fit your deployment
  pdp: "http://localhost:7766",

  // if you want the SDK to emit logs, uncomment this:
  // log: {
  //   level: "debug",
  // },

  // The SDK returns false if you get a timeout / network error
  // if you want it to throw an error instead, and let you handle this, uncomment this:
  // throwOnError: true,
});

Replace YOUR_API_KEY with the actual API key you obtained. Find instructions how to fetch your API key here.

The SDK enforcement functionality - Checking for permissions​

permit.check() is the fundamental SDK function that controls the permissions enforcement in your application code. It acts as a guard of who can do what, based on the policy that you defined.

tip

If you would like to learn more about the permit.check() function, and how it works with different policy models, you can read more about it here.

You can run a permission check with permit.check(), passing in 3 arguments:

  • user: a unique string id or object that identifies the user performing the action.
  • action: the action performed.
  • resource: the resource (object) the action is performed on. Can be a string or an object.
tip

The check function can accept various arguments beyond the user and resource. For more detailed information on these arguments, please refer to the main check page documentation.

In the following example we are checking that a user with the unique id john@smith.com can read a document.

const permitted = await permit.check("john@permit.io", "read", "document");

if (permitted) {
  console.log("John is PERMITTED to read a document");
} else {
  console.log("John is NOT PERMITTED to read a document");
}

Other API configuration functionality with the SDK​

In this quickstart, we'll introduce you to some core Permit.io functionality using the SDK. As you'll see, the SDK is designed to be simple and logical, making it easy to develop and manage policies.

Creating a resource​

A resource is the fundamental building block of a policy. It's what the user can interact with. It could be a 'document', a 'building' or even a 'patient health record'.

await permit.api.resource.create({
  key: "repository",
  name: "Repository",
  actions: {
    clone: {},
    push: {},
    view: {},
  },
});

Creating a new role with permissions​

A role defines a set of resources and the specific actions a user can perform on those resources. A user can only perform these actions if they have been assigned the corresponding role.

await permit.api.roles.create({
    key: "manager",
    name: "Manager",
    permissions: [
      "repository:clone",
      "repository:view",
    ],
  });```

Syncing a user to Permit​

The sync user function allows you to take an existing user from your authentication solution, and add them inside of Permit.

await permit.api.syncUser({
  key: "key",
  email: "example@permit.io",
  first_name: "John",
  last_name: "Smith",
  attributes: {},
});

Assigning a role​

A role assignment, as the name suggests, assigns a specific role with defined permissions to a user identity. This role assignment is specific to a particular tenant.

await permit.api.roleAssignments.assign({
  user,
  role,
  tenant: "default",
  resource_instance: "document:1",
});
note

For a comprehensive overview of the various SDK functions, please refer to the compatibility list of SDK functions available per language.

Working with the full SDK specification​

Congratulations on completing the Quickstart guide for Node.js SDK! By now, you should have a solid understanding of the basics, including setting up your environment, making your first API calls, and handling common tasks.

To further enhance your skills and explore the full capabilities of the Node.js SDK, we highly recommend referring to the comprehensive Node.js SDK reference documentation. There, you will find detailed information on all available methods, classes, and advanced usage scenarios that can help you make the most out of the SDK in your projects.

Contents