Lookup Entity (Data Filtering)

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",
    }
})

{
  "entity_ids": [
    "<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 <code>t1</code> for this field. Required, and must match the pattern \“[a-zA-Z0-9-,]+\“, max 64 bytes.

Body

application/json

metadata

object

PermissionLookupEntityRequestMetadata metadata for the PermissionLookupEntityRequest.

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.

context

object

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

context.tuples

object[]

A repeated field of tuples involved in the operation.

context.attributes

object[]

A repeated field of attributes associated with the operation.

context.attributes.entity

object

Entity represents an entity with a type and an identifier.

context.attributes.attribute

string

context.attributes.value

object

Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message.

Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type.

Example 1: Pack and unpack a message in C++.

Foo foo = ...;
Any any;
any.PackFrom(foo);
...
if (any.UnpackTo(&foo)) {
  ...
}

Example 2: Pack and unpack a message in Java.

Foo foo = ...;
Any any = Any.pack(foo);
...
if (any.is(Foo.class)) {
  foo = any.unpack(Foo.class);
}

Example 3: Pack and unpack a message in Python.

foo = Foo(...)
any = Any()
any.Pack(foo)
...
if any.Is(Foo.DESCRIPTOR):
  any.Unpack(foo)
  ...

Example 4: Pack and unpack a message in Go

 foo := &pb.Foo{...}
 any, err := anypb.New(foo)
 if err != nil {
   ...
 }
 ...
 foo := &pb.Foo{}
 if err := any.UnmarshalTo(foo); err != nil {
   ...
 }

The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z".

JSON

The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example:

package google.profile;
message Person {
  string first_name = 1;
  string last_name = 2;
}

{
  "@type": "type.googleapis.com/google.profile.Person",
  "firstName": <string>,
  "lastName": <string>
}

If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]):

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}

context.data

object

Additional data associated with the context.

Response

200 - application/json

entity_ids

string[]

List of identifiers for entities that match the lookup.

Subject Filtering Lookup Entity (Streaming)

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",
    }
})

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

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

API Documentation

Schema Service

Data Service

Permission Service

Tenancy Service

Bundle Service

Watch Service

​How Lookup Operations Evaluated

Path Parameters

Body

Response

How Lookup Operations Evaluated