openapi: 3.0.3
info:
  contact:
    email: hi@ory.sh
  description: 'Documentation for all of Ory Hydra''s APIs.

    '
  license:
    name: Apache 2.0
  title: Ory Hydra api permission API
  version: ''
tags:
- name: permission
paths:
  /relation-tuples/batch/check:
    post:
      description: To learn how relationship tuples and the check works, head over to [the documentation](https://www.ory.com/docs/keto/concepts/api-overview).
      operationId: batchCheckPermission
      parameters:
      - in: query
        name: max-depth
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/batchCheckPermissionBody'
        x-originalParamName: Body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchCheckPermissionResult'
          description: batchCheckPermissionResult
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      summary: Batch check permissions
      tags:
      - permission
      x-ory-ratelimit-bucket: keto-public-high
  /relation-tuples/check:
    get:
      description: To learn how relationship tuples and the check works, head over to [the documentation](https://www.ory.com/docs/keto/concepts/api-overview).
      operationId: checkPermissionOrError
      parameters:
      - description: Namespace of the Relationship
        in: query
        name: namespace
        schema:
          type: string
      - description: Object of the Relationship
        in: query
        name: object
        schema:
          type: string
      - description: Relation of the Relationship
        in: query
        name: relation
        schema:
          type: string
      - description: SubjectID of the Relationship
        in: query
        name: subject_id
        schema:
          type: string
      - description: Namespace of the Subject Set
        in: query
        name: subject_set.namespace
        schema:
          type: string
      - description: Object of the Subject Set
        in: query
        name: subject_set.object
        schema:
          type: string
      - description: Relation of the Subject Set
        in: query
        name: subject_set.relation
        schema:
          type: string
      - in: query
        name: max-depth
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkPermissionResult'
          description: checkPermissionResult
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkPermissionResult'
          description: checkPermissionResult
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      summary: Check a permission
      tags:
      - permission
      x-ory-ratelimit-bucket: keto-public-high
    post:
      description: To learn how relationship tuples and the check works, head over to [the documentation](https://www.ory.com/docs/keto/concepts/api-overview).
      operationId: postCheckPermissionOrError
      parameters:
      - in: query
        name: max-depth
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postCheckPermissionOrErrorBody'
        x-originalParamName: Body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkPermissionResult'
          description: checkPermissionResult
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkPermissionResult'
          description: checkPermissionResult
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      summary: Check a permission
      tags:
      - permission
      x-ory-ratelimit-bucket: keto-public-high
  /relation-tuples/check/openapi:
    get:
      description: To learn how relationship tuples and the check works, head over to [the documentation](https://www.ory.com/docs/keto/concepts/api-overview).
      operationId: checkPermission
      parameters:
      - description: Namespace of the Relationship
        in: query
        name: namespace
        schema:
          type: string
      - description: Object of the Relationship
        in: query
        name: object
        schema:
          type: string
      - description: Relation of the Relationship
        in: query
        name: relation
        schema:
          type: string
      - description: SubjectID of the Relationship
        in: query
        name: subject_id
        schema:
          type: string
      - description: Namespace of the Subject Set
        in: query
        name: subject_set.namespace
        schema:
          type: string
      - description: Object of the Subject Set
        in: query
        name: subject_set.object
        schema:
          type: string
      - description: Relation of the Subject Set
        in: query
        name: subject_set.relation
        schema:
          type: string
      - in: query
        name: max-depth
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkPermissionResult'
          description: checkPermissionResult
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      summary: Check a permission
      tags:
      - permission
      x-ory-ratelimit-bucket: keto-public-high
    post:
      description: To learn how relationship tuples and the check works, head over to [the documentation](https://www.ory.com/docs/keto/concepts/api-overview).
      operationId: postCheckPermission
      parameters:
      - in: query
        name: max-depth
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postCheckPermissionBody'
        x-originalParamName: Payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkPermissionResult'
          description: checkPermissionResult
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      summary: Check a permission
      tags:
      - permission
      x-ory-ratelimit-bucket: keto-public-high
  /relation-tuples/expand:
    get:
      description: Use this endpoint to expand a relationship tuple into permissions.
      operationId: expandPermissions
      parameters:
      - description: Namespace of the Subject Set
        in: query
        name: namespace
        required: true
        schema:
          type: string
      - description: Object of the Subject Set
        in: query
        name: object
        required: true
        schema:
          type: string
      - description: Relation of the Subject Set
        in: query
        name: relation
        required: true
        schema:
          type: string
      - in: query
        name: max-depth
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/expandedPermissionTree'
          description: expandedPermissionTree
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      summary: Expand a Relationship into permissions.
      tags:
      - permission
      x-ory-ratelimit-bucket: keto-admin-medium
components:
  schemas:
    relationship:
      description: Relationship
      properties:
        namespace:
          description: Namespace of the Relation Tuple
          type: string
        object:
          description: Object of the Relation Tuple
          type: string
        relation:
          description: Relation of the Relation Tuple
          type: string
        subject_id:
          description: 'SubjectID of the Relation Tuple


            Either SubjectSet or SubjectID can be provided.'
          type: string
        subject_set:
          $ref: '#/components/schemas/subjectSet'
      required:
      - namespace
      - object
      - relation
      type: object
    subjectSet:
      properties:
        namespace:
          description: Namespace of the Subject Set
          type: string
        object:
          description: Object of the Subject Set
          type: string
        relation:
          description: Relation of the Subject Set
          type: string
      required:
      - namespace
      - object
      - relation
      type: object
    genericError:
      properties:
        code:
          description: The status code
          example: 404
          format: int64
          type: integer
        debug:
          description: 'Debug information


            This field is often not exposed to protect against leaking

            sensitive information.'
          example: SQL field "foo" is not a bool.
          type: string
        details:
          additionalProperties: {}
          description: Further error details
          type: object
        id:
          description: 'The error ID


            Useful when trying to identify various errors in application logic.'
          type: string
        message:
          description: 'Error message


            The error''s message.'
          example: The resource could not be found
          type: string
        reason:
          description: A human-readable reason for the error
          example: User with ID 1234 does not exist.
          type: string
        request:
          description: 'The request ID


            The request ID is often exposed internally in order to trace

            errors across service architectures. This is often a UUID.'
          example: d7ef54b1-ec15-46e6-bccb-524b82c035e6
          type: string
        status:
          description: The status description
          example: Not Found
          type: string
      required:
      - message
      type: object
    expandedPermissionTree:
      properties:
        children:
          description: The children of the node, possibly none.
          items:
            $ref: '#/components/schemas/expandedPermissionTree'
          type: array
        tuple:
          $ref: '#/components/schemas/relationship'
        type:
          description: 'The type of the node.

            union TreeNodeUnion

            exclusion TreeNodeExclusion

            intersection TreeNodeIntersection

            leaf TreeNodeLeaf

            tuple_to_subject_set TreeNodeTupleToSubjectSet

            computed_subject_set TreeNodeComputedSubjectSet

            not TreeNodeNot

            unspecified TreeNodeUnspecified'
          enum:
          - union
          - exclusion
          - intersection
          - leaf
          - tuple_to_subject_set
          - computed_subject_set
          - not
          - unspecified
          type: string
          x-go-enum-desc: 'union TreeNodeUnion

            exclusion TreeNodeExclusion

            intersection TreeNodeIntersection

            leaf TreeNodeLeaf

            tuple_to_subject_set TreeNodeTupleToSubjectSet

            computed_subject_set TreeNodeComputedSubjectSet

            not TreeNodeNot

            unspecified TreeNodeUnspecified'
      required:
      - type
      type: object
    postCheckPermissionOrErrorBody:
      description: Post Check Permission Or Error Body
      properties:
        namespace:
          description: Namespace to query
          type: string
        object:
          description: Object to query
          type: string
        relation:
          description: Relation to query
          type: string
        subject_id:
          description: 'SubjectID to query


            Either SubjectSet or SubjectID can be provided.'
          type: string
        subject_set:
          $ref: '#/components/schemas/subjectSet'
      type: object
    errorGeneric:
      description: The standard Ory JSON API error format.
      properties:
        error:
          $ref: '#/components/schemas/genericError'
      required:
      - error
      title: JSON API Error Response
      type: object
    batchCheckPermissionResult:
      description: Batch Check Permission Result
      properties:
        results:
          description: An array of check results. The order aligns with the input order.
          items:
            $ref: '#/components/schemas/checkPermissionResultWithError'
          type: array
      required:
      - results
      type: object
    checkPermissionResultWithError:
      description: Check Permission Result With Error
      properties:
        allowed:
          description: whether the relation tuple is allowed
          type: boolean
        error:
          description: any error generated while checking the relation tuple
          type: string
      required:
      - allowed
      type: object
    postCheckPermissionBody:
      description: Check Permission using Post Request Body
      properties:
        namespace:
          description: Namespace to query
          type: string
        object:
          description: Object to query
          type: string
        relation:
          description: Relation to query
          type: string
        subject_id:
          description: 'SubjectID to query


            Either SubjectSet or SubjectID can be provided.'
          type: string
        subject_set:
          $ref: '#/components/schemas/subjectSet'
      type: object
    batchCheckPermissionBody:
      description: Batch Check Permission Body
      properties:
        tuples:
          items:
            $ref: '#/components/schemas/relationship'
          type: array
      type: object
    checkPermissionResult:
      description: The content of the allowed field is mirrored in the HTTP status code.
      properties:
        allowed:
          description: whether the relation tuple is allowed
          type: boolean
      required:
      - allowed
      title: Check Permission Result
      type: object
  securitySchemes:
    basic:
      scheme: basic
      type: http
    bearer:
      scheme: bearer
      type: http
    oauth2:
      flows:
        authorizationCode:
          authorizationUrl: https://hydra.demo.ory.sh/oauth2/auth
          scopes:
            offline: A scope required when requesting refresh tokens (alias for `offline_access`)
            offline_access: A scope required when requesting refresh tokens
            openid: Request an OpenID Connect ID Token
          tokenUrl: https://hydra.demo.ory.sh/oauth2/token
      type: oauth2
x-forwarded-proto: string
x-request-id: string