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

​

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.

​

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”.

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.

​

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.

Example HTTP Request on Postman:

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:

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.

​

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

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 call with one of our Permify engineers. Alternatively you can join our discord community to discuss.