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 API
  version: ''
tags:
- name: api
paths:
  /.well-known/jwks.json:
    get:
      description: This endpoint returns cryptographic keys that are required to, for example, verify signatures of ID Tokens.
      operationId: getWellKnownJSONWebKeys
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jsonWebKeySet'
          description: jsonWebKeySet
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
      summary: Lists Cryptographic Keys
      tags:
      - api
  /decisions:
    get:
      description: '> This endpoint works with all HTTP Methods (GET, POST, PUT, ...) and matches every path prefixed with /decisions.


        This endpoint mirrors the proxy capability of ORY Oathkeeper''s proxy functionality but instead of forwarding the

        request to the upstream server, returns 200 (request should be allowed), 401 (unauthorized), or 403 (forbidden)

        status codes. This endpoint can be used to integrate with other API Proxies like Ambassador, Kong, Envoy, and many more.'
      operationId: decisions
      responses:
        '200':
          $ref: '#/components/responses/emptyResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
      summary: Access Control Decision API
      tags:
      - api
  /rules:
    get:
      description: 'This method returns an array of all rules that are stored in the backend. This is useful if you want to get a full

        view of what rules you have currently in place.'
      operationId: listRules
      parameters:
      - description: The maximum amount of rules returned.
        in: query
        name: limit
        schema:
          format: int64
          type: integer
      - description: The offset from where to start looking.
        in: query
        name: offset
        schema:
          format: int64
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/rules'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
      summary: List All Rules
      tags:
      - api
  /rules/{id}:
    get:
      description: Use this method to retrieve a rule from the storage. If it does not exist you will receive a 404 error.
      operationId: getRule
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/rule'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
          description: genericError
      summary: Retrieve a Rule
      tags:
      - api
components:
  schemas:
    jsonWebKeySet:
      properties:
        keys:
          description: 'The value of the "keys" parameter is an array of JWK values.  By

            default, the order of the JWK values within the array does not imply

            an order of preference among them, although applications of JWK Sets

            can choose to assign a meaning to the order for their purposes, if

            desired.'
          items:
            $ref: '#/components/schemas/jsonWebKey'
          type: array
      type: object
    ruleMatch:
      properties:
        methods:
          description: 'An array of HTTP methods (e.g. GET, POST, PUT, DELETE, ...). When ORY Oathkeeper searches for rules

            to decide what to do with an incoming request to the proxy server, it compares the HTTP method of the incoming

            request with the HTTP methods of each rules. If a match is found, the rule is considered a partial match.

            If the matchesUrl field is satisfied as well, the rule is considered a full match.'
          items:
            type: string
          type: array
        url:
          description: 'This field represents the URL pattern this rule matches. When ORY Oathkeeper searches for rules

            to decide what to do with an incoming request to the proxy server, it compares the full request URL

            (e.g. https://mydomain.com/api/resource) without query parameters of the incoming

            request with this field. If a match is found, the rule is considered a partial match.

            If the matchesMethods field is satisfied as well, the rule is considered a full match.


            You can use regular expressions in this field to match more than one url. Regular expressions are encapsulated in

            brackets < and >. The following example matches all paths of the domain `mydomain.com`: `https://mydomain.com/<.*>`.'
          type: string
      type: object
    genericError:
      description: The standard error format
      properties:
        code:
          format: int64
          type: integer
        details:
          items:
            additionalProperties: {}
            type: object
          type: array
        message:
          type: string
        reason:
          type: string
        request:
          type: string
        status:
          type: string
      type: object
    jsonWebKey:
      properties:
        alg:
          description: 'The "alg" (algorithm) parameter identifies the algorithm intended for

            use with the key.  The values used should either be registered in the

            IANA "JSON Web Signature and Encryption Algorithms" registry

            established by [JWA] or be a value that contains a Collision-

            Resistant Name.'
          type: string
        crv:
          type: string
        d:
          type: string
        dp:
          type: string
        dq:
          type: string
        e:
          type: string
        k:
          type: string
        kid:
          description: 'The "kid" (key ID) parameter is used to match a specific key.  This

            is used, for instance, to choose among a set of keys within a JWK Set

            during key rollover.  The structure of the "kid" value is

            unspecified.  When "kid" values are used within a JWK Set, different

            keys within the JWK Set SHOULD use distinct "kid" values.  (One

            example in which different keys might use the same "kid" value is if

            they have different "kty" (key type) values but are considered to be

            equivalent alternatives by the application using them.)  The "kid"

            value is a case-sensitive string.'
          type: string
        kty:
          description: 'The "kty" (key type) parameter identifies the cryptographic algorithm

            family used with the key, such as "RSA" or "EC". "kty" values should

            either be registered in the IANA "JSON Web Key Types" registry

            established by [JWA] or be a value that contains a Collision-

            Resistant Name.  The "kty" value is a case-sensitive string.'
          type: string
        n:
          type: string
        p:
          type: string
        q:
          type: string
        qi:
          type: string
        use:
          description: 'The "use" (public key use) parameter identifies the intended use of

            the public key. The "use" parameter is employed to indicate whether

            a public key is used for encrypting data or verifying the signature

            on data. Values are commonly "sig" (signature) or "enc" (encryption).'
          type: string
        x:
          type: string
        x5c:
          description: 'The "x5c" (X.509 certificate chain) parameter contains a chain of one

            or more PKIX certificates [RFC5280].  The certificate chain is

            represented as a JSON array of certificate value strings.  Each

            string in the array is a base64-encoded (Section 4 of [RFC4648] --

            not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value.

            The PKIX certificate containing the key value MUST be the first

            certificate.'
          items:
            type: string
          type: array
        y:
          type: string
      type: object
    rule:
      properties:
        authenticators:
          description: 'Authenticators is a list of authentication handlers that will try and authenticate the provided credentials.

            Authenticators are checked iteratively from index 0 to n and if the first authenticator to return a positive

            result will be the one used.


            If you want the rule to first check a specific authenticator  before "falling back" to others, have that authenticator

            as the first item in the array.'
          items:
            $ref: '#/components/schemas/ruleHandler'
          type: array
        authorizer:
          $ref: '#/components/schemas/ruleHandler'
        description:
          description: Description is a human readable description of this rule.
          type: string
        id:
          description: 'ID is the unique id of the rule. It can be at most 190 characters long, but the layout of the ID is up to you.

            You will need this ID later on to update or delete the rule.'
          type: string
        match:
          $ref: '#/components/schemas/ruleMatch'
        mutators:
          description: 'Mutators is a list of mutation handlers that transform the HTTP request. A common use case is generating a new set

            of credentials (e.g. JWT) which then will be forwarded to the upstream server.


            Mutations are performed iteratively from index 0 to n and should all succeed in order for the HTTP request to be forwarded.'
          items:
            $ref: '#/components/schemas/ruleHandler'
          type: array
        upstream:
          $ref: '#/components/schemas/Upstream'
      title: swaggerRule is a single rule that will get checked on every HTTP request.
      type: object
    Upstream:
      properties:
        preserve_host:
          description: 'PreserveHost, if false (the default), tells ORY Oathkeeper to set the upstream request''s Host header to the

            hostname of the API''s upstream''s URL. Setting this flag to true instructs ORY Oathkeeper not to do so.'
          type: boolean
        strip_path:
          description: StripPath if set, replaces the provided path prefix when forwarding the requested URL to the upstream URL.
          type: string
        url:
          description: URL is the URL the request will be proxied to.
          type: string
      type: object
    ruleHandler:
      properties:
        config:
          description: 'Config contains the configuration for the handler. Please read the user

            guide for a complete list of each handler''s available settings.'
        handler:
          description: 'Handler identifies the implementation which will be used to handle this specific request. Please read the user

            guide for a complete list of available handlers.'
          type: string
      type: object
  responses:
    rule:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rule'
      description: A rule
    rules:
      content:
        application/json:
          schema:
            items:
              $ref: '#/components/schemas/rule'
            type: array
      description: A list of rules
    emptyResponse:
      description: An empty response
  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