> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expand Relationships

> Get all users and group relationships associated with an object by role

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:

```http theme={null}
POST /api/permissions/{syncId}/expand
{
  "object": "1f2c08ea-c785-54e2-a9b2-c362364e1d23",
  "relation": "can_read"
}
```

This provides a response like:

```json Response expandable theme={null}
{
  "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):

```http theme={null}
POST /api/permissions/{syncId}/expand
{
  "object": "1f2c08ea-c785-54e2-a9b2-c362364e1d23",
  "relation": "editor"
}
```


## OpenAPI

````yaml post /api/permissions/{syncId}/expand
openapi: 3.0.0
info:
  title: Paragon Sync API
  description: API for managing Syncs and permissions for Connected Users
  version: 1.0.0
servers:
  - url: https://sync.useparagon.com
    description: Production server
security:
  - bearerAuth: []
paths:
  /api/permissions/{syncId}/expand:
    post:
      summary: Expand Relationships
      description: Get all users and group relationships associated with an object by role
      parameters:
        - name: syncId
          in: path
          required: true
          schema:
            type: string
          description: >-
            UUID of the Sync to query, returned from the [Enable
            Sync](/managed-sync/api/enable-a-sync) endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                object:
                  type: string
                  description: >-
                    The UUID of the file object that you are querying
                    relationships for.
                relation:
                  type: string
                  description: >-
                    The role (e.g. `can_read`, `can_write`, `is_owner`) or other
                    relation to query on for this file.
              required:
                - object
                - role
      responses:
        '200':
          description: >-
            Expanded relationships tree showing all users and groups related to
            the object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpandResponse'
components:
  schemas:
    ExpandResponse:
      type: object
      required:
        - tree
      properties:
        tree:
          $ref: '#/components/schemas/UsersetTree'
    UsersetTree:
      type: object
      properties:
        root:
          $ref: '#/components/schemas/Node'
    Node:
      type: object
      properties:
        name:
          type: string
        leaf:
          $ref: '#/components/schemas/Leaf'
        difference:
          $ref: '#/components/schemas/UsersetTreeDifference'
        union:
          $ref: '#/components/schemas/Nodes'
        intersection:
          $ref: '#/components/schemas/Nodes'
    Leaf:
      type: object
      properties:
        users:
          $ref: '#/components/schemas/Users'
        computed:
          $ref: '#/components/schemas/Computed'
        tupleToUserset:
          $ref: '#/components/schemas/UsersetTreeTupleToUserset'
    UsersetTreeDifference:
      type: object
      properties:
        base:
          $ref: '#/components/schemas/Node'
        subtract:
          $ref: '#/components/schemas/Node'
    Nodes:
      type: object
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/Node'
    Users:
      type: object
      properties:
        users:
          type: array
          items:
            type: string
    Computed:
      type: object
      properties:
        userset:
          type: string
    UsersetTreeTupleToUserset:
      type: object
      properties:
        tupleset:
          type: string
        computed:
          type: array
          items:
            $ref: '#/components/schemas/Computed'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Paragon User Token. Add to the Authorization header of your requests.

````