Lookup Entity (Data Filtering)

cr, err := client.Permission.LookupEntity(context.Background(), &v1.PermissionLookupEntityRequest{
    TenantId: "t1",
    Metadata: &v1.PermissionLookupEntityRequestMetadata{
        SnapToken: "",
        SchemaVersion: "",
        Depth: 20,
    },
    EntityType: "document",
    Permission: "edit",
    Subject: &v1.Subject{
        Type: "user",
        Id: "1",
    }
    PageSize: 20,
    ContinuousToken: "",
})

client.permission.lookupEntity({
    tenantId: "t1",
    metadata: {
        snapToken: "",
        schemaVersion: "",
        depth: 20
    },
    entity_type: "document",
    permission: "edit",
    subject: {
        type: "user",
        id: "1"
    },
    page_size: 20,
    continuous_token: ""
}).then((response) => {
    console.log(response.entity_ids)
})

curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permissions/lookup-entity' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata":{
    "snap_token": "",
    "schema_version": "",
    "depth": 20
  },
  "entity_type": "document",
  "permission": "edit",
  "subject": {
    "type":"user",
    "id":"1"
  },
  "page_size": 20,
  "continuous_token": "",
}'

{
  "entity_ids": [
    "<string>"
  ],
  "continuous_token": "<string>"
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

POST

tenants

{tenant_id}

permissions

lookup-entity

cr, err := client.Permission.LookupEntity(context.Background(), &v1.PermissionLookupEntityRequest{
    TenantId: "t1",
    Metadata: &v1.PermissionLookupEntityRequestMetadata{
        SnapToken: "",
        SchemaVersion: "",
        Depth: 20,
    },
    EntityType: "document",
    Permission: "edit",
    Subject: &v1.Subject{
        Type: "user",
        Id: "1",
    }
    PageSize: 20,
    ContinuousToken: "",
})

client.permission.lookupEntity({
    tenantId: "t1",
    metadata: {
        snapToken: "",
        schemaVersion: "",
        depth: 20
    },
    entity_type: "document",
    permission: "edit",
    subject: {
        type: "user",
        id: "1"
    },
    page_size: 20,
    continuous_token: ""
}).then((response) => {
    console.log(response.entity_ids)
})

curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permissions/lookup-entity' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata":{
    "snap_token": "",
    "schema_version": "",
    "depth": 20
  },
  "entity_type": "document",
  "permission": "edit",
  "subject": {
    "type":"user",
    "id":"1"
  },
  "page_size": 20,
  "continuous_token": "",
}'

{
  "entity_ids": [
    "<string>"
  ],
  "continuous_token": "<string>"
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

Lookup Entity endpoint lets you ask questions in form of “Which resources can user:X do action Y?”. As a response of this you’ll get a entity results in a format of string array or as a streaming response depending on the endpoint you’re using. So, we provide 2 separate endpoints for data filtering check request,

Lookup Entity
Lookup Entity Streaming

In this endpoint you’ll get directly the IDs’ of the entities that are authorized in an array.

How Lookup Operations Evaluated

We explicitly designed reverse lookup to be more performant with changing its evaluation pattern. We do not query all the documents in bulk to get response, instead of this Permify first finds the necessary relations with given subject and the permission/action in the API call. Then query these relations with the subject id this way we reduce lots of additional queries. To give an example,

entity user {}

entity organization {
		relation admin @user
}

entity container {
		relation parent @organization
		relation container_admin @user
		action admin = parent.admin or container_admin
}
	
entity document {
		relation container @container
		relation viewer @user
		relation owner @user
		action view = viewer or owner or container.admin
}

Lets say we called (reverse) lookup API to find the documents that user:1 can view. Permify first finds the relations that linked with view action, these are

document#viewer
document#owner
organization#admin
container#``container_admin

Then queries each of them with user:1.

Path Parameters

tenant_id

string

required

Identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant t1 for this field. Required, and must match the pattern \“[a-zA-Z0-9-,]+\“, max 64 bytes.

Body

application/json

PermissionLookupEntityRequest is the request message for the LookupEntity method in the Permission service.

metadata

object

PermissionLookupEntityRequestMetadata metadata for the PermissionLookupEntityRequest.

Show child attributes

entity_type

string

Type of the entity to lookup, required, must start with a letter and can include alphanumeric and underscore, max 64 bytes.

permission

string

Name of the permission to check, required, must start with a letter and can include alphanumeric and underscore, max 64 bytes.

subject

object

Subject represents an entity subject with a type, an identifier, and a relation.

Show child attributes

context

object

Context encapsulates the information related to a single operation, including the tuples involved and the associated attributes.

Show child attributes

scope

object

Scope: A map that associates entity types with lists of identifiers. Each entry helps filter requests by specifying which entities are relevant to the operation.

Show child attributes

page_size

integer<int64>

page_size is the number of entities to be returned in the response. The value should be between 1 and 100.

continuous_token

string

continuous_token is an optional parameter used for pagination. It should be the value received in the previous response.

Response

A successful response.

PermissionLookupEntityResponse is the response message for the LookupEntity method in the Permission service.

entity_ids

string[]

List of identifiers for entities that match the lookup.

continuous_token

string

continuous_token is a string that can be used to paginate and retrieve the next set of results.

API Documentation

Schema Service

Data Service

Permission Service

Tenancy Service

Bundle Service

Watch Service

Lookup Entity (Data Filtering)

How Lookup Operations Evaluated

Path Parameters

Body

Response

​How Lookup Operations Evaluated

Path Parameters

Body

Response

How Lookup Operations Evaluated