Skip to main content

Connect your app and run your first permission check

Connect an application to Permit.io and call permit.check() to allow or deny a request based on the user's role. This tutorial is for backend developers who have a Permit.io policy and want to enforce the policy from code. At the end, you have a running demo application that returns an allow or deny result for each request, and the check appears in the Permit audit log.

Prerequisites​

  • A Permit.io account with at least one policy. If you don't have a policy yet, complete the Quickstart.
  • Docker, if you run the policy decision point (PDP) as a container. See Install Docker.

1. Get your environment API key​

The SDK and the PDP authenticate with Permit using an environment API key. Each API key belongs to one environment.

  1. In the Permit dashboard, open the Projects screen.
  2. Find the project and the environment you want to connect to.
  3. On the environment card, click the Three dots menu icon icon in the top-right corner.
  4. Click Copy API Key.
Projects screen with the environment card menu open and Copy API Key highlighted
Copy the API key from the user menu

You can also copy the API key of the active environment from User Menu > Copy Environment Key.

User menu open with Copy Environment Key highlighted
The user menu copies the active environment's key

The API key you copy from the user menu belongs to the active environment in the sidebar. If you switch the active environment and click Copy Environment Key again, you copy a different API key: the key of the newly active environment.

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.

2. Set up your policy decision point (PDP)​

Your application sends each permission check to a policy decision point (PDP), the service that evaluates the check against your policy. Use the managed Cloud PDP that Permit.io runs, or run the PDP as a Docker container on your machine.

The SDK examples on this page connect to a container PDP at http://localhost:7766. To use the Cloud PDP, set the SDK's PDP URL to https://cloudpdp.api.permit.io instead.

The Cloud PDP needs no installation. Pass the Cloud PDP URL when you initialize the Permit SDK. The following Node.js example shows the shape. The SDK install step further down shows the same setting in this page's language. Replace [YOUR_API_KEY] with your environment API key:

// This line initializes the SDK and connects your app
// to the Permit.io Cloud PDP.

const permit = new Permit({
  pdp: "https://cloudpdp.api.permit.io",
  // your API Key
  token: "[YOUR_API_KEY]",
});
Cloud PDP policy models

The Cloud PDP is a managed service that Permit.io runs. The Cloud PDP supports RBAC (role-based access control) and ReBAC (relationship-based access control) policies. The Cloud PDP does not support ABAC (attribute-based access control) policies, so the ABAC examples on this page need a container PDP.

For capabilities, limits, and when to choose each PDP type, see Cloud PDP capabilities.

3. Install the SDK and check permissions​

Select your language. Each tab installs the Permit.io SDK, creates a client that connects to your PDP, runs permit.check(), and runs a full demo application.

Install and initialize the Node.js SDK​

Install the permitio package, import the Permit class, and create a Permit client that connects to your PDP.

  1. Install the Permit.io Node.js SDK:
npm install permitio
  1. Import the Permit class with an ES module import or a CommonJS require:
import { Permit } from "permitio";
  1. Create a Permit client. Replace [YOUR_API_KEY] with your environment API key, and set pdp to the URL of your PDP:
// This 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 checks: http://localhost:7766 for the container PDP, or https://cloudpdp.api.permit.io for the Cloud PDP.
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.

Check permissions with the Node.js SDK​

Call permit.check() with three arguments. permit.check() returns a promise that resolves to true when the policy allows the action, and false otherwise.

ArgumentDescription
userThe key that identifies the user in Permit, typically the user ID from your authentication provider. To pass attributes, use an object with key and attributes.
actionThe action key, for example create.
resourceThe resource type key, for example document, or an object with type, tenant, and attributes.

This example checks whether the user john@permit.io can create a document:

const permitted = await permit.check("john@permit.io", "create", "document");
if (permitted) {
  console.log("John is PERMITTED to create a document");
} else {
  console.log("John is NOT PERMITTED to create a document");
}

If john@permit.io exists in your environment and has a role that grants create on document, the example prints John is PERMITTED to create a document. Otherwise, the example prints John is NOT PERMITTED to create a document. To add users and assign roles, see Sync users.

Check a permission in a specific tenant​

In a multi-tenant application, pass the tenant key in the tenant field of the resource object. To look up the keys of your tenants, call the list tenants API.

This example checks whether john@permit.io can read documents in the awesome_inc tenant:

const permitted = await permit.check(
  // the key of the user
  "john@permit.io",
  // the action
  "read",
  {
    type: "document",
    tenant: "awesome_inc",
  }
);
Where checks run and where user data is stored

permit.check() sends each check to the PDP URL you configure. A container PDP evaluates checks on your machine, using policy and data that the PDP loads from Permit. Users, roles, and attributes that you create in the dashboard or sync through the Permit API are stored in the Permit control plane.

Check ABAC permissions with the Node.js SDK​

An attribute-based access control (ABAC) policy grants permissions based on user and resource attributes, grouped into user sets and resource sets. See ABAC policy components. ABAC checks need a container PDP.

To check an ABAC policy, pass the user and the resource as objects with just-in-time attributes, which you pass in the check call. In this example, replace check@permit.io, action, resource, and tenant with a user key, action key, resource key, and tenant key from your environment:

const permitted = await permit.check(
  // the user object
  {
    // the user key
    key: "check@permit.io",
    // just-in-time attributes on the user
    attributes: {
      location: "England",
      department: "Engineering",
    },
  },
  // the action the user is trying to do
  "action",
  // Resource
  {
    // the type of the resource (the resource key)
    type: "resource",
    // just-in-time attributes on the resource
    attributes: {
      hasApproval: "true",
    },
    // the tenant the resource belong to
    tenant: "tenant",
  }
);

For more check options, see Check permissions with permit.check().

Run a full Node.js example app​

This single-file Express app runs a permission check on each request to http://localhost:4000.

  1. In a new project directory, install the permitio and express packages with npm install permitio express.
  2. Save the following code as app.js.
  3. Replace [YOUR_API_KEY] with your environment API key, and [A_USER_ID] with the key of a user in your environment.
const { Permit } = require("permitio");

const express = require("express");
const app = express();
const port = 4000;

// This 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({
  // in production, you might need to change this url to fit your deployment
  pdp: "http://localhost:7766",
  // your secret API Key
  token: "[YOUR_API_KEY]",
});

// You can open http://localhost:4000 to invoke this http
// endpoint, and see the outcome of the permission check.
app.get("/", async (req, res) => {
  // Example user object
  // You would usually get the user from your authentication layer (e.g. Auth0, Cognito, etc) via a JWT token or a database.
  const user = {
    key: "[A_USER_ID]",
    firstName: "John",
    lastName: "Smith",
    email: "john@permit.io",
  };

  // check for permissions to a resource and action (in this example, create a document)
  const permitted = await permit.check(user.key, "create", "document");
  if (permitted) {
    res.status(200).send(`${user.firstName} ${user.lastName} is PERMITTED to create document!`);
  } else {
    res.status(403).send(`${user.firstName} ${user.lastName} is NOT PERMITTED to create document!`);
  }
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});
  1. Run node app.js. The terminal prints Example app listening at http://localhost:4000.
  2. Open http://localhost:4000 in a browser.

If the user's role grants create on document, the page returns HTTP 200 with John Smith is PERMITTED to create document!. Otherwise, the page returns HTTP 403 with John Smith is NOT PERMITTED to create document!.

4. Confirm the check in the audit log​

Open the Audit Log screen in the Permit dashboard. Each permit.check() call from your application appears as an entry with the user, the action, the resource, and the decision.

If the check doesn't appear in the audit log, see Troubleshoot audit logs.

Next steps​

Contents

Edit this page

Need help?