---
title: Check Access Control
openapi: post /v1/tenants/{tenant_id}/permissions/check
---

In Permify, you can perform two different types access checks,

- **resource based** authorization checks, structured in the following form: `Can user U perform action Y in resource Z ?`
- **subject based** authorization checks, structured in the following form: `Which resources can user U edit ?`

In this section we'll look at the resource based check request of Permify. 

You can find subject based access checks in [Entity (Data) Filtering] section.

[Entity (Data) Filtering]: ./lookup-entity

## Content 

- [Example Check Requests](#example-check-requests)
    - [Resource Based Access Check (Relationships)](#resource-based-check-relationships)
    - [Attribute Based Access Check With Context Data](#attribute-based-abac-check-with-context-data)
- [How Access Decisions Evaluated?](#how-access-decisions-evaluated)
- [Latency & Performance](#latency-and-performance)
- [Parameters & Properties](#parameters-and-properties)

## Example Check requests

### Resource Based Check (Relationships)

```javascript
POST /v1/permissions/check
```

<Tabs>
<Tab title="Go">

```go
cr, err: = client.Permission.Check(context.Background(), &v1.PermissionCheckRequest {
    TenantId: "t1",
    Metadata: &v1.PermissionCheckRequestMetadata {
        SnapToken: "",
        SchemaVersion: "",
        Depth: 20,
    },
    Entity: &v1.Entity {
        Type: "repository",
        Id: "1",
    },
    Permission: "edit",
    Subject: &v1.Subject {
        Type: "user",
        Id: "1",
    },

    if (cr.can === PermissionCheckResponse_Result.RESULT_ALLOWED) {
        // RESULT_ALLOWED
    } else {
        // RESULT_DENIED
    }
})
```

</Tab>
<Tab title="Node">

```javascript
client.permission.check({
    tenantId: "t1", 
    metadata: {
        snapToken: "",
        schemaVersion: "",
        depth: 20
    },
    entity: {
        type: "repository",
        id: "1"
    },
    permission: "edit",
    subject: {
        type: "user",
        id: "1"
    }
}).then((response) => {
    if (response.can === PermissionCheckResponse_Result.RESULT_ALLOWED) {
        console.log("RESULT_ALLOWED")
    } else {
        console.log("RESULT_DENIED")
    }
})
```

</Tab>
<Tab title="Python">
```python
with permify.ApiClient(configuration) as api_client:
    api_instance = permify.PermissionApi(api_client)
    tenant_id = 't1' 

    body = PermissionsCheckRequest(
        tenant_id=tenant_id,
        metadata={
            "snapToken": "",
            "schemaVersion": "",
            "depth": 20
        },
        entity={
            "type": "repository",
            "id": "1"
        },
        permission="edit",
        subject={
            "type": "user",
            "id": "1"
        }
    )

    try:
        api_response = api_instance.permissions_check(tenant_id, body)
        if api_response.can == PermissionCheckResponse.Result.RESULT_ALLOWED:
            print("RESULT_ALLOWED")
        else:
            print("RESULT_DENIED")
    except ApiException as e:
        print(f"Exception permissions_check: {e}")
```
</Tab>

<Tab title="cURL">
```curl
curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permissions/check' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata":{
    "snap_token": "",
    "schema_version": "",
    "depth": 20
  },
  "entity": {
    "type": "repository",
    "id": "1"
  },
  "permission": "edit",
  "subject": {
    "type": "user",
    "id": "1",
    "relation": ""
  },
}'
```
</Tab>
</Tabs>

### Attribute Based (ABAC) Check With Context Data

```javascript
client.permission.check({
    tenantId: "t1",
    metadata: {
        snapToken: "",
        schemaVersion: "",
        depth: 20,
    },
    entity: {
        type: "organization",
        id: "1",
    },
    permission: "hr_manager",
    subject: {
        type: "user",
        id: "1",
    },
    context: {
        data: {
            ip_address: "192.158.1.38",
        },
    },
}).then((response) => {
    if (response.can === PermissionCheckResponse_Result.RESULT_ALLOWED) {
        console.log("RESULT_ALLOWED");
    } else {
        console.log("RESULT_DENIED");
    }
});
```

## How Access Decisions Evaluated?

Access decisions are evaluated by stored [relational tuples] and your authorization model, [Permify Schema]. 

In high level, access of an subject related with the relationships or attributes created between the subject and the resource. You can define this data in Permify Schema then create and store them as relational tuples and attributes, which is basically forms your authorization data. 

Permify Engine to compute access decision in 2 steps, 
1. Looking up authorization model for finding the given action's ( **edit**, **push**, **delete** etc.) relations.
2. Walk over a graph of each relation to find whether given subject ( user or user set ) is related with the action. 

Let's turn back to above authorization question ( ***"Can the user 3 edit document 12 ?"*** ) to better understand how decision evaluation works. 

[relational tuples]: ../../getting-started/sync-data.md
[Permify Schema]:  ../../getting-started/modeling.md

When Permify Engine receives this question it directly looks up to authorization model to find document `‍edit` action. Let's say we have a model as follows

```perm
entity user {}
        
entity organization {

    // organizational roles
    relation admin @user
    relation member @user
}

entity document {

    // represents documents parent organization
    relation parent @organization
    
    // represents owner of this document
    relation owner  @user
    
    // permissions
    action edit   = parent.admin or owner
    action delete = owner
} 
```

Which has a directed graph as follows:

![relational-tuples](https://github.com/Permify/permify/assets/39353278/cec9936c-f907-42c0-a419-032ebb45454e)

As we can see above: only users with an admin role in an organization, which `document:12` belongs, and owners of the `document:12` can edit. Permify runs two concurrent queries for **parent.admin** and **owner**:

**Q1:** Get the owners of the `document:12`.

**Q2:** Get admins of the organization where `document:12` belongs to.

Since edit action consist **or** between owner and parent.admin, if Permify Engine found user:3 in results of one of these queries then it terminates the other ongoing queries and returns authorized true to the client.

Rather than **or**, if we had an **and** relation then Permify Engine waits the results of these queries to returning a decision. 

## Latency & Performance

With the right architecture we expect **7-12 ms** latency. Depending on your load, cache usage and architecture you can get up to **30ms**.

Permify implements several cache mechanisms in order to achieve low latency in scaled distributed systems. See more on the section [Cache Mechanisims](../../operations/cache) 

## Parameters & Properties