openapi: 3.2.0
info:
  version: 2.2.2
  title: BoB.participantMetadata. Mtb Public Key API
  description: The Participant Metadata API provides an interface for participants to manage metadata coordinated by an Administering Body (AB).
servers:
- url: /api/v2
tags:
- name: mtbPublicKey
  description: 'An MTB public key is used for validating the issuer signature attached to an MTB. MTB keys are immutable. More information about MTB key management and algorithms can be found in MTS4, MTS1 section 2.4 and in the BoB Manual: Key Management → 5.3. Ticketing keys.'
paths:
  /participantMetadata/{pid}/mtbPublicKey:
    get:
      tags:
      - mtbPublicKey
      summary: Get MTB public keys by participant identifier
      description: Get the public component of all current MTB signing keys for a certain participant.
      operationId: getMtbPublicKeys
      parameters:
      - name: pid
        in: path
        description: Participant identifier
        required: true
        schema:
          type: integer
          format: int64
      security:
      - Pop: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/jwkPublic'
        '401':
          description: unauthorised
        '404':
          description: pid not found
    post:
      tags:
      - mtbPublicKey
      summary: Add MTB public key to participant object
      operationId: addMtbPublicKey
      parameters:
      - name: pid
        in: path
        description: Participant identifier
        required: true
        schema:
          type: integer
          format: int64
      security:
      - Pop: []
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
                description: the URL of the newly created key object
        '401':
          description: unauthorised
        '403':
          description: kid re-used, which is not allowed
        '404':
          description: pid not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/jwkPublic'
        description: JWK object
        required: true
  /participantMetadata/{pid}/mtbPublicKey/{kid}:
    get:
      tags:
      - mtbPublicKey
      summary: Get MTB public key by key identifier
      description: Get the public component of an MTB signing key.
      operationId: getMtbPublicKey
      parameters:
      - name: pid
        in: path
        description: Participant identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: kid
        in: path
        description: Key identifier
        required: true
        schema:
          type: string
      security:
      - Pop: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jwkPublic'
        '401':
          description: unauthorised
        '404':
          description: pid/kid not found
    put:
      tags:
      - mtbPublicKey
      summary: Update MTB public key by key identifier.
      description: If you updated your keys, please follow these instructions.
      operationId: updateMtbPublicKey
      parameters:
      - name: pid
        in: path
        description: Participant identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: kid
        in: path
        description: Key Identifier
        required: true
        schema:
          type: string
      security:
      - Pop: []
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
                description: the URL of the newly created key object
        '401':
          description: unauthorised
        '404':
          description: pid/kid not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/jwkPublic'
        description: JWK object
        required: true
    delete:
      tags:
      - mtbPublicKey
      summary: Delete MTB public key by key identifier
      operationId: deleteMtbPublicKey
      parameters:
      - name: pid
        in: path
        description: Participant identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: kid
        in: path
        description: Key identifier
        required: true
        schema:
          type: string
      security:
      - Pop: []
      responses:
        '204':
          description: successful operation
        '401':
          description: unauthorised
        '404':
          description: pid/kid not found
components:
  schemas:
    jwkPublic:
      type: object
      description: Public JSON Web Key (JWK) as defined in <a href="https://tools.ietf.org/html/rfc7517" target="_blank">RFC 7517</a>. Two algorithms are supported&#58; the primary algorithm is EC (kty=EC) and the fallback algorithm is RSA (kty=RSA).
      required:
      - kty
      - kid
      properties:
        kty:
          type: string
          description: JWA key type
          example: EC
        kid:
          type: string
          description: JWK key identifier
          example: 34:20190101_bob_mtb
        crv:
          type: string
          description: Curve type (required for kty=EC)
          example: P-256
        x:
          type: string
          description: EC x coordinate (required for kty=EC)
          example: MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4
        y:
          type: string
          description: EC y coordinate (required for kty=EC)
          example: 4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM
        n:
          type: string
          description: RSA modulus parameter (required for kty=RSA)
          example: 0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbW...
        e:
          type: string
          description: RSA exponent parameter (required for kty=RSA)
          example: AQAB
  securitySchemes:
    Pop:
      description: OAuth 2.0 Proof-of-possession (pop) Token
      type: apiKey
      name: Authorization
      in: header