Quickstart

This guide shows you how to set up Permify in your servers and use it across your applications.

Minimum Requirements

PostgreSQL: Version 13.8 or higher

Please ensure your system meets these requirements before proceeding with the following steps:

1. Set Up & Run Permify Service
2. Model your Authorization with Permify Schema
3. Store Authorization Data & Schema
4. Perform Access Check

Want to walk through this guide 1x1 rather than docs ? schedule a call with an Permify engineer.

Set Up Permify Service

You can run Permify Service with various options but in that tutorial we’ll run it via docker container.

Run From Docker Container

Production usage of Permify needs some configurations such as defining running options, selecting datastore to store authorization data and more.

However, for the sake of this tutorial we’ll not do any configurations and quickly start Permify on your local with running the docker command below:

docker run -p 3476:3476 -p 3478:3478  ghcr.io/permify/permify serve 

This will start Permify with the default configuration options:

• Port 3476 is used to serve the REST API.
• Port 3478 is used to serve the GRPC Service.
• Authorization data stored in memory.

You can examine Deploy using Docker section to get more about the configuration options and learn the full integration to run Permify Service from docker container.

Test your connection

You can test your connection with creating an HTTP GET request,

localhost:3476/healthz

You can use our Postman Collection to work with the API. Also see the Using the API section for details of core endpoints.

Model your Authorization with Permify Schema

After installation completed and Permify server is running, next step is modeling authorization with Permify authorization language - Permify Schema- and configure it to Permify API.

You can define your entities, relations between them and access control decisions of each actions with using Permify Schema.

Creating your authorization model

Permify Schema can be created on our playground as well as in any IDE or text editor. We also have a VS Code extension to ease modeling Permify Schema with code snippets and syntax highlights. Note that on VS code the file with extension is “.perm”.

If you’re planning to test Permify manually, maybe with an API Design platform such as Postman, Insomnia, etc; we’re suggesting using our playground to create model. Because Permify Schema needs to be configured (send to API) in Permify API in a string format. Therefore, created model should be converted to string.

Although, it could easily be done programmatically, it could be little challenging to do it manually. To help on that, we have a button on the playground to copy created model to the clipboard as a string, so you get your model in string format easily.

Let’s create our authorization model. We’ll be using following a simple user-organization authorization case for this guide.

entity user {} 

entity organization {

    relation admin @user    
    relation member @user     
    
    action view_files = admin or member
    action edit_files = admin

} 

We have 2 entities these are “user” and “organization”. Entities represents your main tables. We strongly advise naming entities the same as your original database entities.

Lets roll back our example,

• The user entity represents users. This entity is empty because it’s only responsible for referencing users.

• The organization entity has its own relations (admin and member) which related with user entity. This entity also has 2 actions, respectively:

  • Organization member and admin can view files.
  • Only admins can edit files.

For implementation sake we’ll not dive more deep about modeling but you can find more information about modeling on Modeling Authorization with Permify section. Also you can check out Real World Examples section to better understand some familiar use cases modeled with Permify Schema.

Configuring Schema via API

After modeling completed, you need to send Permify Schema - authorization model - to Write Schema API for configuration of your authorization model on Permify authorization service.

You’ll see tenant_id parameter almost all Permify APIs including Write Schema. With version 0.3.x Permify became a tenancy based authorization infrastructure, and supports multi-tenancy by default so its a mandatory parameter when doing any operations.

We provide a pre-inserted tenant - t1 - for ones that don’t need/want to use multi-tenancy. So, we will be passing t1 to all tenant id parameters throughout this guidance.

Example HTTP Request on Postman:

Required	Argument	Type	Default	Description
[x]	tenant_id	string	-	identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant t1 for this field.
[x]	schema	string	-	Permify Schema as string

POST /v1/tenants/{tenant_id}/schemas/write

Store Authorization Data

After you completed configuration of your authorization model via Permify Schema. Its time to add authorizations data to see Permify in action.

You can write relationships and attributes as ACLs by using Write Data API

For our guide let’s grant one of the team members (Ashley) an admin role.

Example HTTP Request on Postman:

Required	Argument	Type	Default	Description
[x]	tenant_id	string	-	identifier of the tenant, if you are not using multi-tenancy (have only one tenant in your system) use pre-inserted tenant t1 for this field.
[x]	tuples	array	-	Can contain multiple relation tuple object
[x]	entity	object	-	Type and id of the entity. Example: “organization:1”
[x]	relation	string	-	Custom relation name. Eg. admin, manager, viewer etc.
[x]	subject	string	-	User or user set who wants to take the action.
[ ]	schema_version	string	8	Version of the schema

POST /v1/tenants/{tenant_id}/data/write

{
    "metadata": {
        "schema_version": ""
    },
    "tuples": [
        {
       "entity": {
        "type": "organization",
        "id": "1" //Organization identifier
        },
        "relation": "admin",
        "subject": {
            "type": "user",
            "id": "1", //Ashley's identifier
            "relation": ""
        }
    }
    ]
}

Created relationship: organization:1#admin@user:1

Semantics: User 1 (Ashley) has admin role on organization 1.

In ideal production usage Permify stores your authorization data in a database you prefer. You can configure the database with using configuration yaml file or CLI flag options.

But in this tutorial Permify Service running default configurations on local, so authorization data will be stored in memory. You can find more detailed explanation how Permify stores authorization data in Managing Authorization Data section.

Perform Access Check

Finally we’re ready to control authorization. Access decision results computed according to relational tuples and the stored model, Permify Schema action conditions.

Lets get back to our example and perform an example access check via Check API. We want to check whether an specific user has an access to view files in a organization.

Can the user 1 view files on organization 1 ?

POST /v1/tenants/{tenant_id}/permissions/check

Required	Argument	Type	Default	Description
[x]	tenant_id	string	-	identifier of the tenant, if you are not using multi-tenancy (have only one tenant in your system) use pre-inserted tenant t1 for this field.
[x]	entity	object	-	name and id of the entity. Example: organization:1.
[x]	action	string	-	the action the user wants to perform on the resource
[x]	subject	object	-	the user or user set who wants to take the action
[ ]	schema_version	string	-	get results according to given schema version
[ ]	depth	integer	8	-

Request:

{
  "metadata": {
    "schema_version": "",
    "snap_token": "",
    "depth": 20
  },
  "entity": {
    "type": "organization",
    "id": "1"
  },
  "permission": "view_files",
  "subject": {
    "type": "user",
    "id": "1",
    "relation": ""
  },
}

Response

{
  "can": "RESULT_ALLOW",
  "metadata": {
    "check_count": 0
  }
}

See Access Control Check section for learn how access checks works and access decisions evaluated in Permify

Need any help ?

Our team is happy to help you get started with Permify. If you struggle with installation or have any questions, schedule a consultation call with one of our account executivess. Alternatively you can join our discord community to discuss.