Skip to main content
POST /v1/tenants/{tenant_id}/permissions/expand The Expand API retrieves all subjects (users and user sets) that have a relationship or attribute granting the requested permission on the given entity. The response is a user set tree — a recursive structure whose leaf nodes are user IDs or pointers to other <object#relation> pairs.
Expand is designed for auditing and building search indices over access-controlled content — not for per-request access checks. Its traversal of the full permission graph introduces significantly higher latency than the Check API. Do not use it in the hot path of authorization decisions.

​
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
object
required
The entity whose permission tree is being expanded.
​
permission
string
The permission or relation to expand. Must match ^[a-zA-Z_]{1,64}$.
​
context
object
Contextual data for this request.

​
Response

​
tree
object
The expanded permission tree. Leaf nodes contain user IDs; intermediate nodes represent set operations (union, intersection, exclusion) or indirect references to other entity-relation pairs.

​
Example

curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permissions/expand' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata": {
    "schema_version": "",
    "snap_token": ""
  },
  "entity": {
    "type": "repository",
    "id": "1"
  },
  "permission": "push"
}'
Request body 
{
  "metadata": {
    "schema_version": "",
    "snap_token": ""
  },
  "entity": {
    "type": "repository",
    "id": "1"
  },
  "permission": "push"
}
Response 
{
  "tree": {
    "target": {
      "entity": { "type": "repository", "id": "1" },
      "relation": "push"
    },
    "node": {
      "leaf": {
        "subjects": [
          { "type": "user", "id": "1" },
          { "type": "user", "id": "42" }
        ]
      }
    }
  }
}

​
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