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

# Expand API

Retrieve all subjects (users and user sets) that have a relationship or attribute with given entity and permission

Expand API response is represented by a user set tree, whose leaf nodes are user IDs or user sets pointing to other ⟨object#relation⟩ pairs.

<Warning>
  Expand is designed for reasoning the complete set of users that have access to their objects, which allows our users to build efficient search indices for access-controlled content.

  It is not designed to use as a check access. Expand request has a high latency which can cause a performance issues when its used as access check.
</Warning>


## OpenAPI

````yaml post /v1/tenants/{tenant_id}/permissions/expand
openapi: 3.0.0
info:
  title: Permify API
  description: >-
    Permify is an open source authorization service for creating fine-grained
    and scalable authorization systems.
  version: v1.6.10
  contact:
    name: API Support
    url: https://github.com/Permify/permify/issues
    email: hello@permify.co
  license:
    name: AGPL-3.0 license
    url: https://github.com/Permify/permify/blob/master/LICENSE
servers: []
security: []
tags:
  - name: Permission
  - name: Watch
  - name: Schema
  - name: Data
  - name: Bundle
  - name: Tenancy
paths:
  /v1/tenants/{tenant_id}/permissions/expand:
    post:
      tags:
        - Permission
      summary: expand api
      operationId: permissions.expand
      parameters:
        - name: tenant_id
          description: >-
            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.
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Permission.ExpandBody'
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionExpandResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      x-codeSamples:
        - label: go
          lang: go
          source: >-
            cr, err := client.Permission.Expand(context.Background(),
            &v1.PermissionExpandRequest{
                TenantId: "t1",
                Metadata: &v1.PermissionExpandRequestMetadata{
                    SnapToken: "",
                    SchemaVersion: "",
                },
                Entity: &v1.Entity{
                    Type: "repository",
                    Id: "1",
                },
                Permission: "push",
            })
        - label: node
          lang: javascript
          source: |-
            client.permission.expand({
                tenantId: "t1",
                metadata: {
                    snapToken: "",
                    schemaVersion: ""
                },
                entity: {
                    type: "repository",
                    id: "1"
                },
                permission: "push",
            })
        - label: cURL
          lang: curl
          source: >-
            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"
            }'
components:
  schemas:
    Permission.ExpandBody:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PermissionExpandRequestMetadata'
        entity:
          $ref: '#/components/schemas/Entity'
        permission:
          type: string
          description: >-
            Name of the permission to be expanded, not required, must start with
            a letter and can include alphanumeric and underscore, max 64 bytes.
        context:
          $ref: '#/components/schemas/Context'
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/Argument'
          description: Additional arguments associated with this request.
      description: >-
        PermissionExpandRequest is the request message for the Expand method in
        the Permission service.
    PermissionExpandResponse:
      type: object
      properties:
        tree:
          $ref: '#/components/schemas/v1.Expand'
      description: >-
        PermissionExpandResponse is the response message for the Expand method
        in the Permission service.
    Status:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/Any'
    PermissionExpandRequestMetadata:
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the schema.
        snap_token:
          type: string
          description: >-
            The snap token to avoid stale cache, see more details on [Snap
            Tokens](../../operations/snap-tokens).
      description: >-
        PermissionExpandRequestMetadata metadata for the
        PermissionExpandRequest.
    Entity:
      type: object
      properties:
        type:
          type: string
        id:
          type: string
      description: Entity represents an entity with a type and an identifier.
    Context:
      type: object
      properties:
        tuples:
          type: array
          items:
            $ref: '#/components/schemas/Tuple'
          description: A repeated field of tuples involved in the operation.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          description: A repeated field of attributes associated with the operation.
        data:
          type: object
          description: Additional data associated with the context.
      description: |-
        Context encapsulates the information related to a single operation,
        including the tuples involved and the associated attributes.
    Argument:
      type: object
      properties:
        computedAttribute:
          $ref: '#/components/schemas/ComputedAttribute'
      description: >-
        Argument defines the type of argument in a Call. It can be either a
        ComputedAttribute or a ContextAttribute.
    v1.Expand:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/Entity'
        permission:
          type: string
          description: permission is the permission applied to the entity.
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/Argument'
          description: >-
            arguments are the additional information or context used to evaluate
            permissions.
        expand:
          $ref: '#/components/schemas/ExpandTreeNode'
        leaf:
          $ref: '#/components/schemas/ExpandLeaf'
      description: >-
        Expand is used to define a hierarchical structure for permissions.

        It has an entity, permission, and arguments. The node can be either
        another hierarchical structure or a set of subjects.
    Any:
      type: object
      properties:
        '@type':
          type: string
          description: >-
            A URL/resource name that uniquely identifies the type of the
            serialized

            protocol buffer message. This string must contain at least

            one "/" character. The last segment of the URL's path must represent

            the fully qualified name of the type (as in

            `path/google.protobuf.Duration`). The name should be in a canonical
            form

            (e.g., leading "." is not accepted).


            In practice, teams usually precompile into the binary all types that
            they

            expect it to use in the context of Any. However, for URLs which use
            the

            scheme `http`, `https`, or no scheme, one can optionally set up a
            type

            server that maps type URLs to message definitions as follows:


            * If no scheme is provided, `https` is assumed.

            * An HTTP GET on the URL must yield a [google.protobuf.Type][]
              value in binary format, or produce an error.
            * Applications are allowed to cache lookup results based on the
              URL, or have them precompiled into a binary to avoid any
              lookup. Therefore, binary compatibility needs to be preserved
              on changes to types. (Use versioned type names to manage
              breaking changes.)

            Note: this functionality is not currently available in the official

            protobuf release, and it is not used for type URLs beginning with

            type.googleapis.com. As of May 2023, there are no widely used type
            server

            implementations and no plans to implement one.


            Schemes other than `http`, `https` (or the empty scheme) might be

            used with implementation specific semantics.
      additionalProperties: {}
      description: >-
        `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"
            }
    Tuple:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/Entity'
        relation:
          type: string
        subject:
          $ref: '#/components/schemas/Subject'
      description: Tuple is a structure that includes an entity, a relation, and a subject.
    Attribute:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/Entity'
        attribute:
          type: string
          title: Name of the attribute
        value:
          $ref: '#/components/schemas/Any'
      description: >-
        Attribute represents an attribute of an entity with a specific type and
        value.
    ComputedAttribute:
      type: object
      properties:
        name:
          type: string
          title: Name of the computed attribute
      description: ComputedAttribute defines a computed attribute which includes its name.
    ExpandTreeNode:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/ExpandTreeNode.Operation'
        children:
          type: array
          items:
            $ref: '#/components/schemas/v1.Expand'
          title: The children of this tree node
      description: >-
        ExpandTreeNode represents a node in an expansion tree with a specific
        operation and its children.
    ExpandLeaf:
      type: object
      properties:
        subjects:
          $ref: '#/components/schemas/Subjects'
        values:
          $ref: '#/components/schemas/Values'
        value:
          $ref: '#/components/schemas/Any'
      description: >-
        ExpandLeaf is the leaf node of an Expand tree and can be either a set of
        Subjects or a set of Values.
    Subject:
      type: object
      properties:
        type:
          type: string
        id:
          type: string
        relation:
          type: string
      description: >-
        Subject represents an entity subject with a type, an identifier, and a
        relation.
    ExpandTreeNode.Operation:
      type: string
      enum:
        - OPERATION_UNSPECIFIED
        - OPERATION_UNION
        - OPERATION_INTERSECTION
        - OPERATION_EXCLUSION
      default: OPERATION_UNSPECIFIED
      description: >-
        Operation is an enum representing the type of operation to be applied on
        the tree node.
    Subjects:
      type: object
      properties:
        subjects:
          type: array
          items:
            $ref: '#/components/schemas/Subject'
          description: A list of subjects.
      description: Subjects holds a repeated field of Subject type.
    Values:
      type: object
      properties:
        values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Any'

````