openapi: 3.0.1
info:
  description: This is the Identity API for manipulating KeyPairResources
  title: KeyPairResources Identity API
  version: "1"
paths:
  /v1alpha/keypairs:
    get:
      description: Get all KeyPair resources across all Participant Contexts. Requires
        elevated access.
      operationId: getAllKeyPairs
      parameters:
      - in: query
        name: offset
        schema:
          type: integer
          format: int32
          default: 0
      - in: query
        name: limit
        schema:
          type: integer
          format: int32
          default: 50
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/KeyPairResource"
          description: The list of KeyPair resources.
        "400":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: The query was malformed or was not understood by the server.
        "401":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "The request could not be completed, because either the authentication\
            \ was missing or was not valid."
      tags:
      - Key Pairs
  /v1alpha/participants/{participantId}/keypairs:
    get:
      description: Finds all KeyPairResources for a particular ParticipantContext.
      operationId: queryKeyPairByParticipantId
      parameters:
      - in: path
        name: participantId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/KeyPairResource"
          description: The KeyPairResource.
        "400":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "Request body was malformed, or the request could not be processed"
        "401":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "The request could not be completed, because either the authentication\
            \ was missing or was not valid."
        "404":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: A KeyPairResource with the given ID does not exist.
      tags:
      - Key Pairs
    put:
      description: "Adds a new key pair to a ParticipantContext. Note that the key\
        \ pair is either generated, or the private key is expected to be found in\
        \ the vault."
      operationId: addKeyPair
      parameters:
      - in: path
        name: participantId
        required: true
        schema:
          type: string
      - in: query
        name: makeDefault
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KeyDescriptor"
      responses:
        "200":
          description: The KeyPairResource was successfully created and linked to
            the participant.
        "400":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "Request body was malformed, or the request could not be processed"
        "401":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "The request could not be completed, because either the authentication\
            \ was missing or was not valid."
        "404":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: A KeyPairResource with the given ID does not exist.
      tags:
      - Key Pairs
  /v1alpha/participants/{participantId}/keypairs/{keyPairId}:
    get:
      description: Finds a KeyPairResource by ID.
      operationId: getKeyPair
      parameters:
      - description: Base64-Url encode Participant Context ID
        in: path
        name: participantId
        required: true
        schema:
          type: string
      - in: path
        name: keyPairId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeyPairResource"
          description: The KeyPairResource.
        "400":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "Request body was malformed, or the request could not be processed"
        "401":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "The request could not be completed, because either the authentication\
            \ was missing or was not valid."
        "404":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: A KeyPairResource with the given ID does not exist.
      tags:
      - Key Pairs
  /v1alpha/participants/{participantId}/keypairs/{keyPairId}/activate:
    post:
      description: Sets a KeyPairResource to the ACTIVE state. Will fail if the current
        state is anything other than ACTIVE or CREATED.
      operationId: activateKeyPair
      parameters:
      - description: Base64-Url encode Participant Context ID
        in: path
        name: participantId
        required: true
        schema:
          type: string
      - in: path
        name: keyPairId
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The KeyPairResource.
        "400":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "Request body was malformed, or the request could not be processed."
        "401":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "The request could not be completed, because either the authentication\
            \ was missing or was not valid."
        "404":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: A KeyPairResource with the given ID does not exist.
      tags:
      - Key Pairs
  /v1alpha/participants/{participantId}/keypairs/{keyPairId}/revoke:
    post:
      description: "Revokes (=removes) a particular key pair, identified by their\
        \ ID and create a new successor key."
      operationId: revokeKeyPair
      parameters:
      - description: Base64-Url encode Participant Context ID
        in: path
        name: participantId
        required: true
        schema:
          type: string
      - in: path
        name: keyPairId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KeyDescriptor"
      responses:
        "200":
          description: The KeyPairResource was successfully rotated and linked to
            the participant.
        "400":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "Request body was malformed, or the request could not be processed"
        "401":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "The request could not be completed, because either the authentication\
            \ was missing or was not valid."
        "404":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: A KeyPairResource with the given ID does not exist.
      tags:
      - Key Pairs
  /v1alpha/participants/{participantId}/keypairs/{keyPairId}/rotate:
    post:
      description: "Rotates (=retires) a particular key pair, identified by their\
        \ ID and optionally create a new successor key."
      operationId: rotateKeyPair
      parameters:
      - description: Base64-Url encode Participant Context ID
        in: path
        name: participantId
        required: true
        schema:
          type: string
      - in: path
        name: keyPairId
        required: true
        schema:
          type: string
      - in: query
        name: duration
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KeyDescriptor"
      responses:
        "200":
          description: The KeyPairResource was successfully rotated and linked to
            the participant.
        "400":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "Request body was malformed, or the request could not be processed"
        "401":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: "The request could not be completed, because either the authentication\
            \ was missing or was not valid."
        "404":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiErrorDetail"
          description: A KeyPairResource with the given ID does not exist.
      tags:
      - Key Pairs
components:
  schemas:
    ApiErrorDetail:
      type: object
      properties:
        invalidValue:
          type: object
        message:
          type: string
        path:
          type: string
        type:
          type: string
    KeyDescriptor:
      type: object
      properties:
        active:
          type: boolean
        keyGeneratorParams:
          type: object
          additionalProperties:
            type: object
        keyId:
          type: string
        privateKeyAlias:
          type: string
        publicKeyJwk:
          type: object
          additionalProperties:
            type: object
        publicKeyPem:
          type: string
        resourceId:
          type: string
        type:
          type: string
    KeyPairResource:
      type: object
      properties:
        defaultPair:
          type: boolean
        groupName:
          type: string
        id:
          type: string
        keyContext:
          type: string
        keyId:
          type: string
        participantId:
          type: string
        privateKeyAlias:
          type: string
        rotationDuration:
          type: integer
          format: int64
        serializedPublicKey:
          type: string
        state:
          type: integer
          format: int32
        timestamp:
          type: integer
          format: int64
        useDuration:
          type: integer
          format: int64
