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,

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

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

context

object

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

context.attributes

object[]

A repeated field of attributes associated with the operation.

context.attributes.attribute

string

context.attributes.entity

object

Entity represents an entity with a type and an identifier.

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);
}
// or ...
if (any.isSameTypeAs(Foo.getDefaultInstance())) {
  foo = any.unpack(Foo.getDefaultInstance());
}

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.

context.tuples

object[]

A repeated field of tuples involved in the operation.

continuous_token

string

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

entity_type

string

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

metadata

object

PermissionLookupEntityRequestMetadata metadata for the PermissionLookupEntityRequest.

page_size

integer

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

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.

Response

200 - application/json

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

continuous_token

string

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

entity_ids

string[]

List of identifiers for entities that match the lookup.

​How Lookup Operations Evaluated

Path Parameters

Body

JSON

Response

How Lookup Operations Evaluated