openapi: 3.2.0
info:
  version: 2.2.2
  title: BoB.participantMetadata. Authtoken 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: authtokenPublicKey
  description: 'A authtoken public key is used for validating a JSON Web Token (JWT), as defined in RFC 7519, included in the request from a BoB Client. Authtoken keys are immutable. Information about authtoken keys, authentication and authorization within BoB can be found in Chapter 6: API Authentication and Authorization of the BoB Manual.'
paths:
  /participantMetadata/{pid}/authtokenPublicKey:
    get:
      tags:
      - authtokenPublicKey
      summary: Get authtoken public keys by participant identifier
      operationId: getAuthtokenPublicKeys
      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:
      - authtokenPublicKey
      summary: Add authtoken public key to participants object
      operationId: addAuthtokenPublicKey
      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}/authtokenPublicKey/{kid}:
    get:
      tags:
      - authtokenPublicKey
      summary: Get authtoken public key by key identifier
      operationId: getAuthtokenPublicKey
      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:
      - authtokenPublicKey
      summary: Update authtoken public key by key identifier.
      operationId: updateAuthtokenPublicKey
      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:
      - authtokenPublicKey
      summary: Delete authtoken public key by key identifier
      operationId: deleteAuthtokenPublicKey
      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