openapi: 3.0.0
info:
  title: Fence OpenAPI Specification admin/user keys API
  version: 0.1.0
  description: Access management for Gen3 data commons. Code is available on [GitHub](https://github.com/uc-cdis/fence).
  termsOfService: http://cdis.uchicago.edu/terms/
  contact:
    email: cdis@uchicago.edu
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://example.domain/
tags:
- name: keys
  description: Get public keys used to validate JWTs issued by fence
paths:
  /jwt/keys:
    get:
      tags:
      - keys
      summary: Return the public keys which can be used to validate JWTs issued and signed by fence
      operationId: getKeys
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicKeys'
  /.well-known/jwks:
    get:
      tags:
      - keys
      summary: Get JWK Set used by the application
      description: See [RFC 7517](https://tools.ietf.org/html/rfc7517) for detailed specification and an [example response](https://tools.ietf.org/html/rfc7517#appendix-A.1).
      responses:
        '200':
          description: JWKS response
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/JWKS'
components:
  schemas:
    PublicKeys:
      type: object
      properties:
        keys:
          type: array
          description: array of single-entry dictionaries mapping from key id to public key
          items:
            type: array
            description: tuple of `(key_id, public_key)`
            items:
              type: string
      example:
        keys:
        - - public_key_01
          - '-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----'
    JWKS:
      type: object
      properties:
        keys:
          type: array
          description: array of dictionaries of key information
          items:
            type: object
            properties:
              kty:
                type: string
                description: key type ("RSA" in our implementation)
              alg:
                type: string
                description: algorithm ("RS256" in our implementation)
              n:
                type: string
                description: base64-encoded public key modulus
              e:
                type: string
                description: base64-encoded public key exponent
              kid:
                type: string
                description: key ID
      example:
        keys:
        - kty: RSA
          n: 0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw
          e: AQAB
          alg: RS256
          kid: '2011-04-29'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access