Skip to main content

Check permissions with the Node.js SDK

Install the Permit.io Node.js SDK, call permit.check() to allow or deny a request, and create resources, roles, users, and role assignments from code. This quickstart is for backend developers who add authorization to a Node.js service.

Prerequisites​

  • A Permit.io account with at least one policy. If you don't have a policy yet, complete the Quickstart.
  • Your environment API key. See Get your API key.
  • A running policy decision point (PDP), either a container PDP at http://localhost:7766 or the Cloud PDP. See Run the PDP.
  • A Node.js project with npm.

Add the Permit.io Node.js SDK to your project​

1. Install the Permit.io SDK​

In your project directory, run:

npm install permitio

2. Import the SDK into your code​

import { Permit } from "permitio";

3. Create a Permit client​

Create a Permit client. Replace [YOUR_API_KEY] with your environment API key, and set pdp to the URL of your PDP: http://localhost:7766 for a container PDP, or https://cloudpdp.api.permit.io for the Cloud PDP.

// 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",
  // },

  // By default, permit.check() throws on a timeout / network error.
  // To make permit.check() return false instead, uncomment this:
  // throwOnError: false,
});
OptionDescription
tokenYour environment API key.
pdpThe URL of the PDP that evaluates permit.check() calls.
log.levelThe SDK log level, for example "debug".
throwOnErrorSet to true to make permit.check() throw when the PDP request fails, or false to make permit.check() return false instead.
Keep the API key out of source control

Anyone with your environment API key can change that environment's policy and data through the Permit API. Load the API key from an environment variable or a secret store, and don't commit the API key to your repository.

Check permissions with permit.check()​

permit.check() asks the PDP whether a user can perform an action on a resource, based on the policy you defined. permit.check() returns a promise that resolves to true when the policy allows the action, and false otherwise.

ArgumentDescription
userThe user key as a string, or an object with key and attributes. The user key is typically the user ID from your authentication provider.
actionThe action key, for example read.
resourceThe resource type key as a string, for example document, or an object with type, tenant, and attributes.

This example checks whether the user john@permit.io 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");
}

If john@permit.io exists in your environment and has a role that grants read on document, the example prints John is PERMITTED to read a document. Otherwise, the example prints John is NOT PERMITTED to read a document. Each check also appears on the Audit Log screen of the Permit dashboard.

For tenants, attributes, relationships, and the context object, see Check permissions with permit.check().

Manage your policy with the Node.js SDK​

The permit.api methods call the Permit API, not the PDP. Permit stores the resources, roles, users, and role assignments that these methods create in the Permit control plane, and the PDP loads them from Permit.

Create a resource​

A resource is a type of object that users act on, for example a document, a building, or a patient health record. A resource defines the actions users can perform on it.

This example creates a repository resource with clone, push, and view actions.:

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

Create a role with permissions​

A role grants a set of permissions. Each permission has the format <resource key>:<action key>. A user can perform these actions only after you assign the role to the user.

This example creates a manager role that can clone and view a repository:

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

Sync a user to Permit​

Syncing a user creates the user in Permit, or updates the user if a user with the same key exists. Sync each user from your authentication provider before you check the user's permissions. Replace key with the user's ID from your authentication provider.

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

For more options, see Sync users.

Assign a role to a user​

A role assignment gives a user a role in a tenant. This example assigns the manager role to the user john@permit.io in the default tenant. To assign a resource role on one resource instance instead, add resource_instance, for example document:1.

await permit.api.roleAssignments.assign({
  user: "john@permit.io",
  role: "manager",
  tenant: "default",
});

For the SDK methods available in each language, see SDK feature parity.

Node.js SDK reference pages​

Next steps​

Contents

Edit this page

Need help?