Skip to main content
POST
/
api
/
permissions
/
{syncId}
/
expand
Expand Relationships
curl --request POST \
  --url https://sync.useparagon.com/api/permissions/{syncId}/expand \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "object": "<string>",
  "relation": "<string>"
}
'
{
  "tree": {
    "root": {
      "name": "<string>",
      "leaf": {
        "users": {
          "users": [
            "<string>"
          ]
        },
        "computed": {
          "userset": "<string>"
        },
        "tupleToUserset": {
          "tupleset": "<string>",
          "computed": [
            {
              "userset": "<string>"
            }
          ]
        }
      },
      "difference": {
        "base": "<unknown>",
        "subtract": "<unknown>"
      },
      "union": {
        "nodes": "<array>"
      },
      "intersection": {
        "nodes": "<array>"
      }
    }
  }
}
The Expand endpoint can be used to query relationships in the permissions graph, returning all users and sets of users that have a certain relationship type to a given object. This provides visibility into why certain users have access to a file (via direct access, inherited role, group membership, or parent access). Here’s a breakdown of using this endpoint to list all users (and groups) that have a can_read relationship to a file. First, we can call the /expand endpoint to query can_read relationships to a file ID: 
POST /api/permissions/{syncId}/expand
{
  "object": "1f2c08ea-c785-54e2-a9b2-c362364e1d23",
  "relation": "can_read"
}
This provides a response like:
Response
{
  "tree": {
    "root": {
      "name": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#can_read",
      "union": {
        "nodes": [
          {
            "name": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#can_read",
            "leaf": {
              "computed": {
                "userset": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#viewer"
              }
            }
          },
          {
            "name": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#can_read",
            "leaf": {
              "computed": {
                "userset": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#editor"
              }
            }
          },
          {
            "name": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#can_read",
            "leaf": {
              "tupleToUserset": {
                "tupleset": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#parent",
                "computed": [
                  {
                    "userset": "file:db847d33-9272-5f4e-87a9-0b7fde41638f#viewer"
                  }
                ]
              }
            }
          },
          {
            "name": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#can_read",
            "leaf": {
              "tupleToUserset": {
                "tupleset": "file:de087147-d851-5f18-ba1f-79e84ff09b0c#space",
                "computed": [
                  {
                    "userset": "space:42d2e50f-2e93-5f14-98c3-911c9a3fdb39#viewer"
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}
This tells us that the users / groups that can read this file can be found in relations:
  1. Users with the viewer role explicitly assigned to this file
  2. Users with the editor role explicitly assigned to this file
  3. Users with the viewer role to the parent of this file (file:db847d33-9272-5f4e-87a9-0b7fde41638f)
  4. Users with the viewer role to the space to which this file belongs (space:42d2e50f-2e93-5f14-98c3-911c9a3fdb39)
We can then query the Expand API again for any of these relations, e.g. the below request for #2 (all editors directly assigned to this file): 
POST /api/permissions/{syncId}/expand
{
  "object": "1f2c08ea-c785-54e2-a9b2-c362364e1d23",
  "relation": "editor"
}

Authorizations

​
Authorization
string
header
required

Paragon User Token. Add to the Authorization header of your requests.

Path Parameters

​
syncId
string
required

UUID of the Sync to query, returned from the Enable Sync endpoint.

Body

application/json
​
object
string
required

The UUID of the file object that you are querying relationships for.

​
relation
string
required

The role (e.g. can_read, can_write, is_owner) or other relation to query on for this file.

Response

200 - application/json

Expanded relationships tree showing all users and groups related to the object

​
tree
object
required