Skip to main content
Version: 2.0.0

Quickstart

Welcome to the Permit Quickstart guide. In the next 15 minutes you should have a simple App running that works flawlessly and enforces users and their roles about what they can and cannot do.

In this tutorial, we will show you how to integrate Permit.io with your application in just a few simple steps.

Get your Permit.io Environment API Key​

Via the projects screen​

  1. Open the Permit.io Dashboard.
  2. Navigate to the Projects screen.
  3. Find the project and environment you wish to connect to.
  4. Click on the context menu of the environment at the top right corner of the environment card.
  5. Click on the Copy API Key option.
Copy secret key from user menu

From the user menu on the sidebar​

You can quickly copy the Environment API Key of the active environment by clicking on the user menu and then on the Copy SDK API Key option.

Copy secret key from Projects management

Remember

The API Key that you will copy from the user menu is linked to the active environment on the sidebar. Switching to another active environment and then clicking on the Copy SDK API Key option will copy a different API Key - the API key of the newly activated environment.

Setup your PDP (Policy Decision Point) Container​

We provide you with a Policy-Decision-Point - aka an authorization microservice. It's available as a docker container for you to use, or we can provide you with a cloud version for quick experimentation.

It is extremely simple to utilize the cloud PDP. As part of the initialization of the Permit instance, you need to pass the cloud PDP URL.

note

The cloud PDP is great for quick experimentation with Permit, to learn how the service works and to quickly integrate the SDK.

However for production deployments it is best to deploy the Docker Container PDP - for better latency and availability.

For time being, the cloud PDP does not support ABAC (Attribute-based Access Control).

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

Select your language​

Add the SDK to your JS code​

Initialise the Node.js SDK and check for permissions.

  1. Install the Permit.io SDK
npm install permitio
  1. Import the SDK into your code
import { Permit } from "permitio";
  1. Create a new instance of the SDK.
    You can find instructions on getting a secret API key in the previous section.
// 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",
  // },
});

Check for permissions using the SDK​

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

  • user: a unique string id that identifies the user doing the action. This is typically the user key.
  • action: the action performed.
  • resource: the resource (object) the action is performed on.

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

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");
}
info

Usually instead of an email you'd use the unique identifier provided by your chosen authentication solution. You can also pass the entire decoded JWT, to include attributes about the user.

REMEMBER

In cases where you are dealing with more than one tenant in your application, permit.check() can pass the tenant as part of the resource.

The tenant passed in needs to be either the tenant id or the tenant key.

You can use the list_tenants API to get the ids and keys set for your tenants.

tenant: a unique tenant id or tenant key that you have defined within Permit.

For example, if we want to check if john@permit.io can read documents that belong to 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",
  }
);

Check permissions against ABAC policies​

Above we have checked for permissions against an RBAC policy - but what if we have an ABAC policy we want to run a permission check for? An ABAC policy is made up of User Sets and Resource Sets, which you can read more about here.

With ABAC we define conditions based on pre-configured attributes.

If we are running a permit.check() for an ABAC policy, we can attach just-in-time attributes to the user and the resource. There attributes are merged (and override) user and resource attributes that were persisted to the permit API.

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",
  }
);
REMEMBER

Permission checks are being run against the PDP container that's running locally on your machine - offering minimal latency and without leaving your network.

This means that your user data never goes outside your system, keeping security high.

Full app example​

Assuming a Node.js app made up of a single file, with the permitio and express modules installed.

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}`);
});
LOGS

Navigate to the audit log page to see your permissions request results.

Don't see logs? Use the troubleshooting page to find reasons why.


note

More SDK functionality coming soon.

Contents