openapi: 3.0.0
info:
  title: Public Key API
  description: |-
    API for retrieving the public key for doing the payload encryption.
  contact:
    email: paymentAPIPNSupport@bmo.com
  version: 1.0.0
servers:
  - url: https://APIHostName
components:
  parameters:
    x-api-key:
      in: header
      name: x-api-key
      description: Unique identifier to identify API and to manage the API usage.
      required: true
      schema:
        type: string
    x-client-id:
      in: header
      name: x-client-id
      description: Used to identify the entity making the API call.
      required: true
      schema:
        type: string
    x-request-id:
      in: header
      name: x-request-id
      description: Unique id used to identify the request.
      required: true
      schema:
        type: string
    x-request-timestamp:
      in: header
      name: x-request-timestamp
      description: Request Timestamp in UTC format. For example 2025-01-22T12:00:00.002 #UTC timezone.
      required: true
      schema:
        type: string
  responses:
    '200':
      description: Success responses
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicKeyResponse'
    '401':
      description: Unauthorized - Request is not having valid authorization credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002 #UTC timezone.
    '429':
      description: Too many requests. System will retry for this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002 #UTC timezone.
    '500':
      description: Internal Server Error or Unexptected Error. System will retry for this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002 #UTC timezone.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key to authenticate the request
  schemas:
    PublicKeyResponse:
      type: object
      required:
        - keyId
        - algorithm
        - publicKey
        - issuedAt
      properties:
        keyId:
          type: string
          description: Unique identifier for this key version.
        algorithm:
          type: string
          description: 'Encryption algorithm to use with this key. We use RSA-OAEP-256'
        publicKey:
          type: string
          description: 'PEM-encoded public key'
          example: "----BEGIN PUBLIC KEY---\nMIIIB"
        validUntil:
          type: string
          description: 'Timestamp in ISO 8601 format'
          example: "2025-01-22T12:00:00.002" #UTC
        issuedAt:
          type: string
          description: 'Timestamp in ISO 8601 format'
          example: "2025-01-22T12:00:00.002" #UTC
    Problem:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.                 
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem. example: Connection to database timed out
paths:
  /public-keys/v1:
    post:
      summary: Get Current Public Key for Encryption
      parameters:
        - $ref: '#/components/parameters/x-api-key'
        - $ref: '#/components/parameters/x-client-id'
        - $ref: '#/components/parameters/x-request-id'
        - $ref: '#/components/parameters/x-request-timestamp'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
