openapi: 3.0.3
info:
  title: Authzed SpiceDB Experimental Permissions API
  description: SpiceDB Permissions API — gRPC and HTTP/JSON interfaces for writing schemas, managing relationship tuples, and executing permission checks using a Zanzibar-inspired graph model. Supports CheckPermission, LookupResources, LookupSubjects, WriteRelationships, ReadRelationships, DeleteRelationships, WriteSchema, ReadSchema, and streaming Watch operations.
  version: '1.0'
  contact:
    name: Authzed, Inc.
    url: https://github.com/authzed/api
    email: support@authzed.com
  license:
    name: Apache 2.0 License
    url: https://github.com/authzed/api/blob/main/LICENSE
servers:
- url: https://grpc.authzed.com
  description: Authzed Cloud primary endpoint
- url: https://app.authzed.com
  description: Authzed Cloud management endpoint
security:
- BearerAuth: []
tags:
- name: Permissions
  description: Check, expand, and lookup permissions on resources and subjects
paths:
  /v1/permissions/check:
    post:
      operationId: PermissionsService_CheckPermission
      summary: 'CheckPermission determines for a given resource whether a subject computes

        to having a permission or is a direct member of a particular relation.'
      tags:
      - Permissions
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckPermissionRequest'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckPermissionResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1/permissions/checkbulk:
    post:
      operationId: PermissionsService_CheckBulkPermissions
      summary: 'CheckBulkPermissions evaluates the given list of permission checks

        and returns the list of results.'
      tags:
      - Permissions
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckBulkPermissionsRequest'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckBulkPermissionsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1/permissions/expand:
    post:
      operationId: PermissionsService_ExpandPermissionTree
      summary: 'ExpandPermissionTree reveals the graph structure for a resource''s

        permission or relation. This RPC does not recurse infinitely deep and may

        require multiple calls to fully unnest a deeply nested graph.'
      tags:
      - Permissions
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpandPermissionTreeRequest'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpandPermissionTreeResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1/permissions/resources:
    post:
      operationId: PermissionsService_LookupResources
      summary: 'LookupResources returns all the resources of a given type that a subject

        can access whether via a computed permission or relation membership.'
      tags:
      - Permissions
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupResourcesRequest'
      responses:
        '200':
          description: A successful response.(streaming responses)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/LookupResourcesResponse'
                  error:
                    $ref: '#/components/schemas/Status'
                title: Stream result of LookupResourcesResponse
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1/permissions/subjects:
    post:
      operationId: PermissionsService_LookupSubjects
      summary: 'LookupSubjects returns all the subjects of a given type that

        have access whether via a computed permission or relation membership.'
      tags:
      - Permissions
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupSubjectsRequest'
      responses:
        '200':
          description: A successful response.(streaming responses)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/LookupSubjectsResponse'
                  error:
                    $ref: '#/components/schemas/Status'
                title: Stream result of LookupSubjectsResponse
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    SubProblems:
      type: object
      properties:
        traces:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/CheckDebugTrace'
    CheckBulkPermissionsRequest:
      type: object
      properties:
        consistency:
          $ref: '#/components/schemas/Consistency'
        items:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/CheckBulkPermissionsRequestItem'
        withTracing:
          type: boolean
          description: 'with_tracing, if true, indicates that each response should include a debug trace.

            This can be useful for debugging and performance analysis, but adds a small amount

            of compute overhead to the request.'
      description: 'CheckBulkPermissionsRequest issues a check on whether a subject has permission

        or is a member of a relation on a specific resource for each item in the list.


        The ordering of the items in the response is maintained in the response.

        Checks with the same subject/permission will automatically be batched for performance optimization.'
    Any:
      type: object
      properties:
        '@type':
          type: string
          description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n  value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n  URL, or have them precompiled into a binary to avoid any\n  lookup. Therefore, binary compatibility needs to be preserved\n  on changes to types. (Use versioned type names to manage\n  breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
      additionalProperties: {}
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n    // or ...\n    if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n      foo = any.unpack(Foo.getDefaultInstance());\n    }\n\n Example 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\n Example 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := anypb.New(foo)\n     if err != nil {\n       ...\n     }\n     ...\n     foo := &pb.Foo{}\n     if err := any.UnmarshalTo(foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }"
    LookupResourcesResponse:
      type: object
      properties:
        lookedUpAt:
          $ref: '#/components/schemas/ZedToken'
          description: looked_up_at is the ZedToken at which the resource was found.
        resourceObjectId:
          type: string
          description: resource_object_id is the object ID of the found resource.
        permissionship:
          $ref: '#/components/schemas/LookupPermissionship'
          title: permissionship indicates whether the response was partially evaluated or not
        partialCaveatInfo:
          $ref: '#/components/schemas/PartialCaveatInfo'
          title: partial_caveat_info holds information of a partially-evaluated caveated response
        afterResultCursor:
          $ref: '#/components/schemas/v1.Cursor'
          description: 'after_result_cursor holds a cursor that can be used to resume the LookupResources stream after this

            result.'
      description: 'LookupResourcesResponse contains a single matching resource object ID for the

        requested object type, permission, and subject.'
    CheckPermissionResponse:
      type: object
      properties:
        checkedAt:
          $ref: '#/components/schemas/ZedToken'
        permissionship:
          $ref: '#/components/schemas/CheckPermissionResponse.Permissionship'
          description: 'Permissionship communicates whether or not the subject has the requested

            permission or has a relationship with the given resource, over the given

            relation.


            This value will be authzed.api.v1.PERMISSIONSHIP_HAS_PERMISSION if the

            requested subject is a member of the computed permission set or there

            exists a relationship with the requested relation from the given resource

            to the given subject.'
        partialCaveatInfo:
          $ref: '#/components/schemas/PartialCaveatInfo'
          title: partial_caveat_info holds information of a partially-evaluated caveated response
        debugTrace:
          $ref: '#/components/schemas/DebugInformation'
          description: debug_trace is the debugging trace of this check, if requested.
        optionalExpiresAt:
          type: string
          format: date-time
          description: 'optional_expires_at is the time at which at least one of the relationships used to

            compute this result, expires (if any). This is *not* related to the caching window.'
    ResolvedSubject:
      type: object
      properties:
        subjectObjectId:
          type: string
          description: 'subject_object_id is the Object ID of the subject found. May be a `*` if

            a wildcard was found.'
        permissionship:
          $ref: '#/components/schemas/LookupPermissionship'
          title: permissionship indicates whether the response was partially evaluated or not
        partialCaveatInfo:
          $ref: '#/components/schemas/PartialCaveatInfo'
          title: partial_caveat_info holds information of a partially-evaluated caveated response
      description: ResolvedSubject is a single subject resolved within LookupSubjects.
    PermissionType:
      type: string
      enum:
      - PERMISSION_TYPE_UNSPECIFIED
      - PERMISSION_TYPE_RELATION
      - PERMISSION_TYPE_PERMISSION
      default: PERMISSION_TYPE_UNSPECIFIED
    LookupSubjectsResponse:
      type: object
      properties:
        lookedUpAt:
          $ref: '#/components/schemas/ZedToken'
        subjectObjectId:
          type: string
          title: 'subject_object_id is the Object ID of the subject found. May be a `*` if

            a wildcard was found.

            deprecated: use `subject`'
        excludedSubjectIds:
          type: array
          items:
            type: string
          title: 'excluded_subject_ids are the Object IDs of the subjects excluded. This list

            will only contain object IDs if `subject_object_id` is a wildcard (`*`) and

            will only be populated if exclusions exist from the wildcard.

            deprecated: use `excluded_subjects`'
        permissionship:
          $ref: '#/components/schemas/LookupPermissionship'
          title: 'permissionship indicates whether the response was partially evaluated or not

            deprecated: use `subject.permissionship`'
        partialCaveatInfo:
          $ref: '#/components/schemas/PartialCaveatInfo'
          title: 'partial_caveat_info holds information of a partially-evaluated caveated response

            deprecated: use `subject.partial_caveat_info`'
        subject:
          $ref: '#/components/schemas/ResolvedSubject'
          description: subject is the subject found, along with its permissionship.
        excludedSubjects:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/ResolvedSubject'
          description: 'excluded_subjects are the subjects excluded. This list

            will only contain subjects if `subject.subject_object_id` is a wildcard (`*`) and

            will only be populated if exclusions exist from the wildcard.'
        afterResultCursor:
          $ref: '#/components/schemas/v1.Cursor'
          description: 'after_result_cursor holds a cursor that can be used to resume the LookupSubjects stream after this

            result.'
      description: 'LookupSubjectsResponse contains a single matching subject object ID for the

        requested subject object type on the permission or relation.'
    CheckDebugTrace:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ObjectReference'
          description: 'resource holds the resource on which the Check was performed.

            for batched calls, the object_id field contains a comma-separated list of object IDs

            for all the resources checked in the batch.'
        permission:
          type: string
          description: permission holds the name of the permission or relation on which the Check was performed.
        permissionType:
          $ref: '#/components/schemas/PermissionType'
          description: permission_type holds information indicating whether it was a permission or relation.
        subject:
          $ref: '#/components/schemas/SubjectReference'
          description: 'subject holds the subject on which the Check was performed. This will be static across all calls within

            the same Check tree.'
        result:
          $ref: '#/components/schemas/CheckDebugTrace.Permissionship'
          description: result holds the result of the Check call.
        caveatEvaluationInfo:
          $ref: '#/components/schemas/CaveatEvalInfo'
          description: caveat_evaluation_info holds information about the caveat evaluated for this step of the trace.
        duration:
          type: string
          description: duration holds the time spent executing this Check operation.
        wasCachedResult:
          type: boolean
          description: was_cached_result, if true, indicates that the result was found in the cache and returned directly.
        subProblems:
          $ref: '#/components/schemas/SubProblems'
          description: 'sub_problems holds the sub problems that were executed to resolve the answer to this Check. An empty list

            and a permissionship of PERMISSIONSHIP_HAS_PERMISSION indicates the subject was found within this relation.'
        optionalExpiresAt:
          type: string
          format: date-time
          description: 'optional_expires_at is the time at which at least one of the relationships used to

            compute this result, expires (if any). This is *not* related to the caching window.'
        traceOperationId:
          type: string
          description: 'trace_operation_id is a unique identifier for this trace''s operation, that will

            be shared for all traces created for the same check operation in SpiceDB.


            In cases where SpiceDB performs automatic batching of subproblems, this ID can be used

            to correlate work that was shared across multiple traces.


            This identifier is generated by SpiceDB, is to be considered opaque to the caller

            and only guaranteed to be unique within the same overall Check or CheckBulk operation.'
        source:
          type: string
          description: 'source holds the source of the result. It is of the form:

            `<sourcetype>:<sourceid>`, where sourcetype can be, among others:

            `spicedb`, `materialize`, etc.'
      description: 'CheckDebugTrace is a recursive trace of the requests made for resolving a CheckPermission

        API call.'
    ZedToken:
      type: object
      properties:
        token:
          type: string
      description: 'ZedToken represents a point in time, or a "revision" in SpiceDB.

        It is used to provide causality metadata between Write and read requests (Check, ReadRelationships, LookupResources, LookupSubjects)

        and can also be used to start watching for changes from a specific point in time.


        See the authzed.api.v1.Consistency message for more information.'
    v1.Cursor:
      type: object
      properties:
        token:
          type: string
      description: 'Cursor is used to provide resumption of listing between calls to APIs

        such as LookupResources.'
    Status:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: 'The status code, which should be an enum value of

            [google.rpc.Code][google.rpc.Code].'
        message:
          type: string
          description: 'A developer-facing error message, which should be in English. Any

            user-facing error message should be localized and sent in the

            [google.rpc.Status.details][google.rpc.Status.details] field, or localized

            by the client.'
        details:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Any'
          description: 'A list of messages that carry the error details.  There is a common set of

            message types for APIs to use.'
      description: 'The `Status` type defines a logical error model that is suitable for

        different programming environments, including REST APIs and RPC APIs. It is

        used by [gRPC](https://github.com/grpc). Each `Status` message contains

        three pieces of data: error code, error message, and error details.


        You can find out more about this error model and how to work with it in the

        [API Design Guide](https://cloud.google.com/apis/design/errors).'
    Result:
      type: string
      enum:
      - RESULT_UNSPECIFIED
      - RESULT_UNEVALUATED
      - RESULT_FALSE
      - RESULT_TRUE
      - RESULT_MISSING_SOME_CONTEXT
      default: RESULT_UNSPECIFIED
    AlgebraicSubjectSet:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/AlgebraicSubjectSet.Operation'
        children:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/PermissionRelationshipTree'
      description: 'AlgebraicSubjectSet is a subject set which is computed based on applying the

        specified operation to the operands according to the algebra of sets.


        UNION is a logical set containing the subject members from all operands.


        INTERSECTION is a logical set containing only the subject members which are

        present in all operands.


        EXCLUSION is a logical set containing only the subject members which are

        present in the first operand, and none of the other operands.'
    ObjectReference:
      type: object
      properties:
        objectType:
          type: string
        objectId:
          type: string
      description: ObjectReference is used to refer to a specific object in the system.
    WildcardOption:
      type: string
      enum:
      - WILDCARD_OPTION_UNSPECIFIED
      - WILDCARD_OPTION_INCLUDE_WILDCARDS
      - WILDCARD_OPTION_EXCLUDE_WILDCARDS
      default: WILDCARD_OPTION_UNSPECIFIED
    ExpandPermissionTreeRequest:
      type: object
      properties:
        consistency:
          $ref: '#/components/schemas/Consistency'
        resource:
          $ref: '#/components/schemas/ObjectReference'
          description: resource is the resource over which to run the expansion.
        permission:
          type: string
          description: 'permission is the name of the permission or relation over which to run the

            expansion for the resource.'
      description: 'ExpandPermissionTreeRequest returns a tree representing the expansion of all

        relationships found accessible from a permission or relation on a particular

        resource.


        ExpandPermissionTreeRequest is typically used to determine the full set of

        subjects with a permission, along with the relationships that grant said

        access.'
    CaveatEvalInfo:
      type: object
      properties:
        expression:
          type: string
          description: expression is the expression that was evaluated.
        result:
          $ref: '#/components/schemas/Result'
          description: result is the result of the evaluation.
        context:
          type: object
          description: context consists of any named values that were used for evaluating the caveat expression.
        partialCaveatInfo:
          $ref: '#/components/schemas/PartialCaveatInfo'
          description: partial_caveat_info holds information of a partially-evaluated caveated response, if applicable.
        caveatName:
          type: string
          description: caveat_name is the name of the caveat that was executed, if applicable.
      description: CaveatEvalInfo holds information about a caveat expression that was evaluated.
    DebugInformation:
      type: object
      properties:
        check:
          $ref: '#/components/schemas/CheckDebugTrace'
          description: check holds debug information about a check request.
        schemaUsed:
          type: string
          description: schema_used holds the schema used for the request.
      description: 'DebugInformation defines debug information returned by an API call in a footer when

        requested with a specific debugging header.


        The specific debug information returned will depend on the type of the API call made.


        See the github.com/authzed/authzed-go project for the specific header and footer names.'
    LookupPermissionship:
      type: string
      enum:
      - LOOKUP_PERMISSIONSHIP_UNSPECIFIED
      - LOOKUP_PERMISSIONSHIP_HAS_PERMISSION
      - LOOKUP_PERMISSIONSHIP_CONDITIONAL_PERMISSION
      default: LOOKUP_PERMISSIONSHIP_UNSPECIFIED
      description: "- LOOKUP_PERMISSIONSHIP_UNSPECIFIED: LOOKUP_PERMISSIONSHIP_UNSPECIFIED is the default value and should not be used or\nrelied upon. Servers should not return this value.\n - LOOKUP_PERMISSIONSHIP_HAS_PERMISSION: LOOKUP_PERMISSIONSHIP_HAS_PERMISSION indicates that the subject has permission\non the resource with no missing caveat context.\n - LOOKUP_PERMISSIONSHIP_CONDITIONAL_PERMISSION: LOOKUP_PERMISSIONSHIP_CONDITIONAL_PERMISSION indicates that the subject has\npermission on the resource, but only if a caveat condition is met. The\n`partial_caveat_info` field in the response should contain the missing context\nfields that must be provided to fully evaluate the caveat."
      title: LookupPermissionship represents whether a Lookup response was partially evaluated or not
    CheckPermissionResponse.Permissionship:
      type: string
      enum:
      - PERMISSIONSHIP_UNSPECIFIED
      - PERMISSIONSHIP_NO_PERMISSION
      - PERMISSIONSHIP_HAS_PERMISSION
      - PERMISSIONSHIP_CONDITIONAL_PERMISSION
      default: PERMISSIONSHIP_UNSPECIFIED
      description: " - PERMISSIONSHIP_UNSPECIFIED: PERMISSIONSHIP_UNSPECIFIED is the default value and should not be used or\nrelied upon. Servers should not return this value.\n - PERMISSIONSHIP_NO_PERMISSION: PERMISSIONSHIP_NO_PERMISSION indicates that the subject does not have the\nrequested permission on the resource.\n - PERMISSIONSHIP_HAS_PERMISSION: PERMISSIONSHIP_HAS_PERMISSION indicates that the subject has the requested\npermission on the resource.\n - PERMISSIONSHIP_CONDITIONAL_PERMISSION: PERMISSIONSHIP_CONDITIONAL_PERMISSION indicates that the subject has the\nrequested permission on the resource, but only if a caveat condition is met.\nThe `partial_caveat_info` field in the response should contain the missing\ncontext fields that must be provided to fully evaluate the caveat."
    PartialCaveatInfo:
      type: object
      properties:
        missingRequiredContext:
          type: array
          items:
            type: string
          title: 'missing_required_context is a list of one or more fields that were missing and prevented caveats

            from being fully evaluated'
      title: 'PartialCaveatInfo carries information necessary for the client to take action

        in the event a response contains a partially evaluated caveat'
    SubjectReference:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/ObjectReference'
        optionalRelation:
          type: string
      title: 'SubjectReference is used for referring to the subject portion of a

        Relationship. The relation component is optional and is used for defining a

        sub-relation on the subject, e.g. group:123#members'
    CheckPermissionRequest:
      type: object
      properties:
        consistency:
          $ref: '#/components/schemas/Consistency'
        resource:
          $ref: '#/components/schemas/ObjectReference'
          description: resource is the resource on which to check the permission or relation.
        permission:
          type: string
          description: 'permission is the name of the permission (or relation) on which to execute

            the check.'
        subject:
          $ref: '#/components/schemas/SubjectReference'
          description: subject is the subject that will be checked for the permission or relation.
        context:
          type: object
          title: context consists of named values that are injected into the caveat evaluation context
        withTracing:
          type: boolean
          description: 'with_tracing, if true, indicates that the response should include a debug trace.

            This can be useful for debugging and performance analysis, but adds a small amount

            of compute overhead to the request.'
      description: 'CheckPermissionRequest issues a check on whether a subject has a permission

        or is a member of a relation, on a specific resource.'
    CheckDebugTrace.Permissionship:
      type: string
      enum:
      - PERMISSIONSHIP_UNSPECIFIED
      - PERMISSIONSHIP_NO_PERMISSION
      - PERMISSIONSHIP_HAS_PERMISSION
      - PERMISSIONSHIP_CONDITIONAL_PERMISSION
      default: PERMISSIONSHIP_UNSPECIFIED
    LookupResourcesRequest:
      type: object
      properties:
        consistency:
          $ref: '#/components/schemas/Consistency'
        resourceObjectType:
          type: string
          description: 'resource_object_type is the type of resource object for which the IDs will

            be returned.'
        permission:
          type: string
          description: 'permission is the name of the permission or relation for which the subject

            must Check.'
        subject:
          $ref: '#/components/schemas/SubjectReference'
          description: subject is the subject with access to the resources.
        context:
          type: object
          title: context consists of named values that are injected into the caveat evaluation context
        optionalLimit:
          type: integer
          format: int64
          description: 'optional_limit, if non-zero, specifies the limit on the number of resources to return

            before the stream is closed on the server side. By default, the stream will continue

            resolving resources until exhausted or the stream is closed due to the client or a

            network issue.'
        optionalCursor:
          $ref: '#/components/schemas/v1.Cursor'
          description: 'optional_cursor, if specified, indicates the cursor after which results should resume being returned.

            The cursor can be found on the LookupResourcesResponse object.'
        withDebug:
          type: boolean
          description: 'with_debug, if true, indicates that the response should return debug information

            if present and available. For now, ONLY enables debugging of maximum recursion depth

            errors, with additional context being returned in error details, but this may be

            extended in the future.'
      description: 'LookupResourcesRequest performs a lookup of all resources of a particular

        kind on which the subject has the specified permission or the relation in

        which the subject exists, streaming back the IDs of those resources.'
    CheckBulkPermissionsResponseItem:
      type: object
      properties:
        permissionship:
          $ref: '#/components/schemas/CheckPermissionResponse.Permissionship'
        partialCaveatInfo:
          $ref: '#/components/schemas/PartialCaveatInfo'
        debugTrace:
          $ref: '#/components/schemas/DebugInformation'
          description: debug_trace is the debugging trace of this check, if requested.
    AlgebraicSubjectSet.Operation:
      type: string
      enum:
      - OPERATION_UNSPECIFIED
      - OPERATION_UNION
      - OPERATION_INTERSECTION
      - OPERATION_EXCLUSION
      default: OPERATION_UNSPECIFIED
    DirectSubjectSet:
      type: object
      properties:
        subjects:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/SubjectReference'
      description: DirectSubjectSet is a subject set which is simply a collection of subjects.
    CheckBulkPermissionsPair:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/CheckBulkPermissionsRequestItem'
        item:
          $ref: '#/components/schemas/CheckBulkPermissionsResponseItem'
        error:
          $ref: '#/components/schemas/Status'
    LookupSubjectsRequest:
      type: object
      properties:
        consistency:
          $ref: '#/components/schemas/Consistency'
        resource:
          $ref: '#/components/schemas/ObjectReference'
          description: 'resource is the resource for which all matching subjects for the permission

            or relation will be returned.'
        permission:
          type: string
          description: 'permission is the name of the permission (or relation) for which to find

            the subjects.'
        subjectObjectType:
          type: string
          description: 'subject_object_type is the type of subject object for which the IDs will

            be returned.'
        optionalSubjectRelation:
          type: string
          description: optional_subject_relation is the optional relation for the subject.
        context:
          type: object
          title: context consists of named values that are injected into the caveat evaluation context
        optionalConcreteLimit:
          type: integer
          format: int64
          description: 'optional_concrete_limit is currently unimplemented for LookupSubjects

            and will return an error as of SpiceDB version 1.40.1. This will

            be implemented in a future version of SpiceDB.'
        optionalCursor:
          $ref: '#/components/schemas/v1.Cursor'
          description: 'optional_cursor is not currently supported for LookupSubjects and this

            field will be ignored. Cursoring support will be added in a future version.'
        wildcardOption:
          $ref: '#/components/schemas/WildcardOption'
          description: 'wildcard_option specifies whether wildcards should be returned by LookupSubjects.

            For backwards compatibility, defaults to WILDCARD_OPTION_INCLUDE_WILDCARDS if unspecified.'
      description: 'LookupSubjectsRequest performs a lookup of all subjects of a particular

        kind for which the subject has the specified permission or the relation in

        which the subject exists, streaming back the IDs of those subjects.'
    CheckBulkPermissionsRequestItem:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ObjectReference'
        permission:
          type: string
        subject:
          $ref: '#/components/schemas/SubjectReference'
        context:
          type: object
    Consistency:
      type: object
      properties:
        minimizeLatency:
          type: boolean
          description: 'minimize_latency indicates that the latency for the call should be

            minimized by having the system select the fastest snapshot available.'
        atLeastAsFresh:
          $ref: '#/components/schemas/ZedToken'
          description: 'at_least_as_fresh indicates that all data used in the API call must be

            *at least as fresh* as that found in the ZedToken; more recent data might

            be used if available or faster.'
        atExactSnapshot:
          $ref: '#/components/schemas/ZedToken'
          description: 'at_exact_snapshot indicates that all data used in the API call must be

            *at the given* snapshot in time; if the snapshot is no longer available,

            an error will be returned to the caller.'
        fullyConsistent:
          type: boolean
          description: 'fully_consistent indicates that all data used in the API call *must* be

            at the most recent snapshot found.


            NOTE: using this method can be *quite slow*, so unless there is a need to

            do so, it is recommended to use `at_least_as_fresh` with a stored

            ZedToken.'
      description: 'Consistency will define how a request is handled by the backend.

        By defining a consistency requirement, and a token at which those

        requirements should be applied, where applicable.'
    ExpandPermissionTreeResponse:
      type: object
      properties:
        expandedAt:
          $ref: '#/components/schemas/ZedToken'
        treeRoot:
          $ref: '#/components/schemas/PermissionRelationshipTree'
          description: 'tree_root is a tree structure whose leaf nodes are subjects, and

            intermediate nodes represent the various operations (union, intersection,

            exclusion) to reach those subjects.'
    CheckBulkPermissionsResponse:
      type: object
      properties:
        checkedAt:
          $ref: '#/components/schemas/ZedToken'
        pairs:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/CheckBulkPermissionsPair'
    PermissionRelationshipTree:
      type: object
      properties:
        intermediate:
          $ref: '#/components/schemas/AlgebraicSubjectSet'
        leaf:
          $ref: '#/components/schemas/DirectSubjectSet'
        expandedObject:
          $ref: '#/components/schemas/ObjectReference'
        expandedRelation:
          type: string
      description: 'PermissionRelationshipTree is used for representing a tree of a resource and

        its permission relationships with other objects.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'SpiceDB preshared-key. Pass as Authorization: Bearer <preshared-key>'