NodeJS Quickstart
In this tutorial, we will show you how to integrate Permit.io with your application in just a few simple steps.
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.
- Cloud PDP
- Container PDP
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.
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]",
});
Please follow the steps below to install and run the container on your local machine.
1. Pull our PDP container from Docker Hub
If you do not have Docker installed as of yet, click here to install Docker.
docker pull permitio/pdp-v2:latest
2. Get the Permit.io API key
Navigate to the Projects page with the Permit.io web interface. Find the active environment that is marked with a green dot on the icon. Copy the Secret Key.
In the left navigation panel inside the Permit.io app, click on your user icon and copy the SDK API Key.

Alternatively, you can navigate to the Projects panel, and underneath an existing project, for each environment, you will be able to access and copy an environment specific SDK API Key.
The SDK API KEY that is available for you to copy from your main user icon is the API Key that reflect the current project and the current environement you are in.

3. Run the container
Remember to replace <YOUR_API_KEY>
with the Secret Key you have just obtained in the previous step.
docker run -p 7766:7000 --env PDP_API_KEY=<YOUR_API_KEY> permitio/pdp-v2:latest
Congratulations! You should now have a PDP container running. You can always check the status of the container
by typing docker ps
in your terminal.
Let's now add the Permit SDK to your app or use the following demo example below.
Add the SDK to your JS code
Initialise the Node.js SDK and check for permissions.
- Install the Permit.io SDK
npm install permitio@next
- Import the SDK into your code
const { Permit } = require("permitio");
- 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({
// in production, you might need to change this url to fit your deployment
pdp: "http://localhost:7766",
// your API Key
token: "[YOUR_API_KEY]",
});
Check for permissions using the SDK
You can run a permission check with permit.check()
. You need to pass 3 arguments to the function:
user.id
: a unique user id or user email that identifies the user doing the action.action
: the action performed.resource
: the resource the action is performed on.
In the following example we are checking that a user with the unique id john@permit.io
can create
a document
resource.
const permitted = await permit.check("john@permit.io", "create", "document");
if (permitted) {
console.log("User is PERMITTED to create a document");
} else {
console.log("User is NOT PERMITTED to create a document");
}
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.
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.
const permitted = await permit.check("userId", "action", {
type: "resource",
tenant: "tenant",
});
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 replace the userId
and the resource
with objects, containing attributes.
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",
}
);
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 = {
id: "[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.id, "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}`);
});