Skip to main content
POST /v1/tenants/{tenant_id}/permissions/lookup-entity Lookup Entity answers subject-based authorization questions of the form: “Which documents can user:1 edit?” Instead of querying every entity in bulk, Permify first resolves the relations linked to the requested permission in the schema, then queries those relations for the given subject — significantly reducing the number of database queries required. Results are returned as a paginated array of entity IDs. Use the continuous_token in the response to retrieve subsequent pages for large datasets.

​
Path Parameters

​
tenant_id
string
required
The tenant identifier. Use t1 for single-tenant deployments. Must match ^([a-zA-Z0-9_\-@\.:+]{1,128}|\*)$.

​
Request Body

​
metadata
object
required
​
entity_type
string
required
The type of entity to look up (e.g. document, repository). Must match ^[a-zA-Z_]{1,64}$.
​
permission
string
required
The permission or relation to evaluate (e.g. edit, view). Must match ^[a-zA-Z_]{1,64}$.
​
subject
object
required
The subject for whom authorized entities are being looked up.
​
context
object
Contextual data for this request.
​
page_size
integer
Number of entity IDs to return per page. Must be >= 1.
​
continuous_token
string
Pagination token returned by the previous response. Omit for the first page.

​
Response

​
entity_ids
array
List of entity IDs the subject has the requested permission on.
​
continuous_token
string
Pagination token for retrieving the next page. Empty when there are no more results.

​
Example

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": ""
}'
Request body 
{
  "metadata": {
    "snap_token": "",
    "schema_version": "",
    "depth": 20
  },
  "entity_type": "document",
  "permission": "edit",
  "subject": {
    "type": "user",
    "id": "1"
  },
  "page_size": 20,
  "continuous_token": ""
}
Response 
{
  "entity_ids": ["1", "3", "7"],
  "continuous_token": ""
}

​
Error Codes

HTTP StatusDescription
400Bad request — invalid fields
401Unauthorized
404Tenant not found
429Rate limit exceeded
500Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us