holder.yml

openapi: 3.0.0
servers:
  - url: https://verifier.qa.veres.app/verifiers/z1A45ZhWEGMeibHrB15nv8Gk6
    description: Veres Verifier (Quality Assurance)
info:
  version: "0.0.3-unstable"
  title: VC Holder API
  description: This is an Experimental Open API Specification for the [VC Data Model](https://www.w3.org/TR/vc-data-model/).
  license:
    name: W3C Software and Document License
    url: http://www.w3.org/Consortium/Legal/copyright-software.
  contact:
    name: GitHub Source Code
    url: https://github.com/w3c-ccg/vc-api
paths:
  /credentials/{id}:
    get:
      tags:
       - Credentials
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      summary: Gets a credential or verifiable credential by ID. To get a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead.
      x-expectedCaller: "Issuer Coordinator"
      operationId: getCredential
      parameters:
        - $ref: "./components/parameters/path/ObjectId.yml"
      responses:
        "200":
          description: Credential retrieved
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "./components/Credential.yml#/components/schemas/Credential"
                  - $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
        "400":
          description: Bad Request
        "401":
          description: Not Authorized
        "404":
          description: Credential not found
        "410":
          description: Gone! There is no data here
        "418":
          description: I'm a teapot - MUST not be returned outside of pre-arranged scenarios between both parties
    delete:
      tags:
       - Credentials
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      summary: Deletes a credential or verifiable credential by ID. To delete a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead.
      x-expectedCaller: "Issuer Coordinator"
      operationId: deleteCredential
      parameters:
        - $ref: "./components/parameters/path/ObjectId.yml"
      responses:
        "202":
          description: Credential deleted - this is a 202 by default as soft deletes and processing time are assumed
        "400":
          description: Bad Request
        "401":
          description: Not Authorized
        "404":
          description: Credential not found
        "410":
          description: Gone! There is no data here
  /credentials:
    get:
      tags:
       - Credentials
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      summary: Gets list of credentials or verifiable credentials
      operationId: getCredentials
      x-expectedCaller: "Holder Coordinator or Issuer Coordinator"
      parameters:
        - in: query
          name: type
          schema:
            type: array
            items:
              type: string
              pattern: "(credentials|verifiablecredentials|all)"
      responses:
        "200":
          description: Credentials retrieved
          content:
            application/json:
              schema:
                type: array
                description: The Credentials
                items:
                  anyOf:
                    - $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
                    - $ref: "./components/Credential.yml#/components/schemas/Credential"
        "400":
          description: Bad Request
        "401":
          description: Not Authorized
        "410":
          description: Gone! There is no data here
  /credentials/derive:
    post:
      tags:
       - Credentials
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      summary: Derives a credential and returns it in the response body.
      operationId: deriveCredential
      description: Derives a credential and returns it in the response body.
      x-expectedCaller: "Holder Coordinator"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeriveCredentialRequest"
        description: Parameters for deriving the credential.
      responses:
        "201":
          description: Credential derived successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeriveCredentialResponse"
        "400":
          description: Invalid Request

  /presentations/{id}:
    get:
      tags:
       - Presentations
      summary: Gets a presentation or verifiable presentation by ID
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: getPresentation
      x-expectedCaller: "Holder Coordinator"
      parameters:
        - $ref: "./components/parameters/path/ObjectId.yml"
      responses:
        "200":
          description: Credential retrieved
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "./components/Presentation.yml#/components/schemas/Presentation"
                  - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
        "400":
          description: Bad Request
        "401":
          description: Not Authorized
        "404":
          description: Presentation not found
        "410":
          description: Gone! There is no data here
    delete:
      tags:
       - Presentations
      summary: Deletes a presentation or verifiable presentation by ID
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: deletePresentation
      x-expectedCaller: "Holder Coordinator"
      parameters:
        - $ref: "./components/parameters/path/ObjectId.yml"
      responses:
        "202":
          description: Presentation deleted - this is a 202 by default as soft deletes and processing time are assumed
        "400":
          description: Bad Request
        "401":
          description: Not Authorized
        "404":
          description: Presentation not found
        "410":
          description: Gone! There is no data here
  /presentations:
    get:
      tags:
       - Presentations
      summary: Gets list of presentations or verifiable presentations
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: getPresentations
      x-expectedCaller: "Holder Coordinator"
      parameters:
        - in: query
          name: type
          schema:
            type: array
            items:
              type: string
              pattern: "(presentations|verifiablepresentations|all)"
      responses:
        "200":
          description: Presentations retrieved
          content:
            application/json:
              schema:
                type: array
                description: The Presentations
                items:
                  anyOf:
                    - $ref: "./components/Presentation.yml#/components/schemas/Presentation"
                    - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
        "400":
          description: Bad Request
        "401":
          description: Not Authorized
        "410":
          description: Gone! There is no data here
    post:
      summary: Creates a presentation and returns it in the response body.
      tags:
       - Presentations
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: createPresentation
      x-expectedCaller: "Holder Coordinator"
      description: Creates a presentation and returns it in the response body.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePresentationRequest"
        description: Parameters for creating the presentation.
      responses:
        "201":
          description: Presentation successfully created!
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePresentationResponse"
        "400":
          description: invalid input!
  /exchanges:
    get:
      summary: Provides a discovery endpoint for the exchanges supported by this server endpoint.
      tags:
       - Exchanges
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: discoverExchanges
      description:
        This endpoint returns an array of the exchange-ids (path endpoints) supported by this server,
        and the associated protocol supported by each exchange endpoint. The list supports pagination.

        Clients consuming this list and wishing to use an exchange endpoint MUST recognize and support
        the protocol identified in the value field. Clients are not expected to dynamically process
        the protocol specified.
      parameters:
        - name: index
          in: query
          description:
            The starting index for the list that is meaningful to the server.
            If omitted, the server must assume the start of the list.

          required: false
          schema:
            type: string
        - name: limit
          in: query
          description:
            The maximum number of items to return in the response. If omitted, the service should

            return all remaining items from the start index.
          required: false
          schema:
            type: number
      responses:
        "200":
          description: A map of the exchange-id endpoints to protocols those exchanges support.
          content:
            application/json:
              schema:
                required:
                  - count
                  - index
                  - total
                  - exchanges
                properties:
                  count:
                    type: number
                    description: The number of elements returned in the array.
                  total:
                    type: number
                    description: The total number of elements available.
                  exchanges:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: the path name of the exchange endpoint. May be a UUID.

                        type:
                          type: string
                          description: MUST be a string that references the protocol supported on that endpoint.
                  index:
                    type: object
                    properties:
                      self:
                        type: string
                        description:
                          The index position of the start of the returned list. Examples could be a numerical value,

                          a URL, or a value meaningful to the server.
                      next:
                        type: string
                        description:
                          The index position for the next set of results (i.e., index of the end of this list).
                          Examples could be a numerical value, a URL, or a value meaningful to the server.


              example:
                {
                  "count": 3,
                  "total": 8,
                  "exchanges" : [
                    {
                      "id" : "credential-refresh",
                      "type": "CredentialRefresh2020"
                    },
                    {
                      "id": "34901-18388409-1939",
                      "type" : "PresentationExchange1.0",
                    },
                    {
                      "id" : "salad",
                      "type" : "https://example.com/oas/my-salad.yml"
                  }],
                  "index": {
                    "self": "0",
                    "next" : "3"
                  }
                }
        "400":
          description: invalid input

  /exchanges/{exchange-id}:
    post:
      summary: Initiates an exchange of information.
      tags:
       - Exchanges
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: initiateExchange
      description:
        A client can use this endpoint to initiate an exchange of a particular
        type. The client can include HTTP POST information related to the
        details of exchange it would like to initiate. If the server understands
        the request, it returns a Verifiable Presentation Request. A request
        that the server cannot understand results in an error.
      parameters:
        - $ref: "./components/parameters/path/ExchangeId.yml"
      requestBody:
        description:
          Information related to the type of exchange the client would like
          to start.
        content:
          application/json:
            schema:
              anyOf:
                -
                  {
                    "type": "object",
                    "description": "Data necessary to initiate the exchange."
                  }
                -
                  $ref: "#/components/schemas/NotifyPresentationAvailableRequest"
      responses:
        "200":
          description: Proceed with exchange.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifiablePresentationRequestBody"
        "400":
          description: Request is malformed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /exchanges/{exchange-id}/{transaction-id}:
    post:
      summary: Receives information related to an existing exchange.
      tags:
       - Exchanges
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
       - didAuth: []
      operationId: receiveExchangeData
      description:
        A client can use this endpoint to continue the exchange of information
        associated with an initiated exchange by sending a Verifiable Presentation
        with information requested by the server to this endpoint.
      parameters:
        - $ref: "./components/parameters/path/ExchangeId.yml"
        - $ref: "./components/parameters/path/TransactionId.yml"
      requestBody:
        description:
          A Verifiable Presentation.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifiablePresentationBody"
      responses:
        "200":
          description: Received data was accepted.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/VerifiablePresentationBody"
                  - $ref: "#/components/schemas/VerifiablePresentationRequestBody"
        "400":
          description: Received data is malformed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The associated exchange or transaction was not found.

components:
  securitySchemes:
    $ref: "./components/SecuritySchemes.yml#/components/securitySchemes"
  schemas:
    DeriveCredentialRequest:
      type: object
      properties:
        verifiableCredential:
          $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
        options:
          $ref: "./components/DeriveCredentialOptions.yml#/components/schemas/DeriveCredentialOptions"
    DeriveCredentialResponse:
      $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
    CreatePresentationRequest:
      type: object
      properties:
        presentation:
          $ref: "./components/Presentation.yml#/components/schemas/Presentation"
        options:
          $ref: "./components/PresentCredentialOptions.yml#/components/schemas/PresentCredentialOptions"
    CreatePresentationResponse:
      type: object
      properties:
        verifiablePresentation:
          $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
    NotifyPresentationAvailableRequest:
      type: object
      properties:
        query:
          type: object
          description: See https://w3c-ccg.github.io/vp-request-spec/#format
          properties:
            type:
              type: string
              description: "The type of query the server should reply with."
            credentialQuery:
              type: object
              description: "Details of the client's available presentation"
      example:
        {
          "query":
            [
              {
                "type": "RequestQueryByFrame",
                "credentialQuery":
                  [
                    {
                      "type":
                        [
                            "VerifiableCredential",
                            "CommercialInvoiceCertificate",
                        ],
                      "reason": "Wallet XYZ is ready to selectively disclose new credentials.",
                    },
                  ],
              },
            ],
        }
    ErrorResponse:
      $ref: "./components/ErrorResponse.yml#/components/schemas/ErrorResponse"
    StorePresentationRequest:
      $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
    VerifiablePresentationRequestBody:
      type: object
      properties:
        verifiablePresentationRequest:
          $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest"
    VerifiablePresentationBody:
      type: object
      properties:
        verifiablePresentation:
          $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"