Skip to main content
Version: 2.0.0

Ruby Quickstart

In this tutorial, we will show you how to integrate 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.

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 Cloud PDP.

const permit = new Permit({
pdp: "",
// your API Key
token: "[YOUR_API_KEY]",

Add the SDK to your Ruby code

Initialise the Ruby SDK and check for permissions.

  1. Install the SDK for Ruby
gem install permit-sdk
  1. Import the SDK into your code
require 'permit-sdk'
  1. Create a new instance of the SDK.
    You can find instructions on getting a secret API key in the previous section.
require 'permit-sdk'
permit ="TOKEN", "localhost:7766") # the PDP url is optional

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: a unique user that identifies the user doing the action - this can be created using hash or a string.
  • action: the action performed, as string.
  • resource: the resource the action is performed on - this can be created using a hash or a string.

In the following examples we are checking that a user with the unique key can create a document resource.

Here is an example using strings:

require 'permit-sdk'
permit ="TOKEN", "localhost:7766") # the PDP url is optional

permitted = permit.check("", "create" , "document")
if permitted
puts " is permitted to create a document"
puts " is not permitted to create a document"

And here is an example using Hash objects:

require 'permit-sdk'
permit ="TOKEN", "localhost:7766") # the PDP url is optional

user_hash = {"key": "", "first_name": "john", "last_name": "doe", "email": ""}
resource_hash = {"type": "document", "tenant": "default"}
permitted = permit.check(user_hash, "create" , resource_hash)
if permitted
puts " is permitted to create a document"
puts " 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 like we showed before in the Hash objects example.

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.

if permit.check("user", "action", { "key": "resource", "tenant": "tenant" })
# Allow to close document

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.

if permit.check(user, 'close', { "key": "resource", "attributes": {"hasApproval": "true"} })
# Allow to close document

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 Ruby app made up of a single file, with the permit-sdk and webrick gem packages installed with the following command :

gem install permit-sdk webrick

Here is a full example of a Ruby app that uses the SDK to check for permissions:

require 'webrick'
require 'permit'

permit ="<YOUR_API_KEY>")

server = 4000)

server.mount_proc '/' do |_, res|
res['Content-Type'] = 'application/json'

permitted = permit.check("", "read", "document")
if permitted
res.status = 200
res.body = { result: " is PERMITTED to read document!" }.to_json
res.status = 403
res.body = { result: " is NOT PERMITTED to read document" }.to_json

trap 'INT' do server.shutdown end