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
      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
        "500":
          description: Internal Error
        "501":
          description: Not Implemented
    delete:
      tags:
       - Credentials
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      summary: Deletes a credential or verifiable credential by ID
      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
        "500":
          description: Internal Error
        "501":
          description: Not Implemented
  /credentials:
    get:
      tags:
       - Credentials
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      summary: Gets list of credentials or verifiable credentials
      operationId: getCredentials
      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
        "500":
          description: Internal Error
        "501":
          description: Not Implemented
  /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.
      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
        "500":
          description: Internal Error
        "501":
          description: Not Implemented

  /presentations/{id}:
    get:
      tags:
       - Presentations
      summary: Gets a presentation or verifiable presentation by ID
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: getPresentation
      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
        "500":
          description: Internal Error
        "501":
          description: Not Implemented
    delete:
      tags:
       - Presentations
      summary: Deletes a presentation or verifiable presentation by ID
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: deletePresentation
      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
        "500":
          description: Internal Error
        "501":
          description: Not Implemented
  /presentations:
    get:
      tags:
       - Presentations
      summary: Gets list of presentations or verifiable presentations
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: getPresentations
      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
        "500":
          description: Internal Error
        "501":
          description: Not Implemented

  /presentations/prove:
    post:
      summary: Proves a presentation and returns it in the response body.
      tags:
       - Presentations
      security:
       - networkAuth: []
       - oAuth2: []
       - zCap: []
      operationId: provePresentation
      description: Proves a presentation and returns it in the response body.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProvePresentationRequest"
        description: Parameters for proving the presentation.
      responses:
        "201":
          description: Presentation successfully proved!
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProvePresentationResponse"
        "400":
          description: invalid input!
        "500":
          description: error!
  /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 that exchange endpoint. The list supports pagination.
        Clients consuming this list 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 supported protocol 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 numerica value,
                          a URL, or a value meaningful to the server.
                      next:
                        type: string
                        description:
                          The index position for the next set of results (ie, index of the end of this list).
                          Examples could be a numerica 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
        "500" :
          description: error

  /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"
        "501":
          description: Service not implemented.
        "500":
          description: Internal server error.
  /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.
        "500":
          description: Internal server error.
        "501":
          description: Service not implemented.

components:
  securitySchemes:
    $ref: "./components/SecuritySchemes.yml#/components/securitySchemes"
  schemas:
    DeriveCredentialRequest:
      type: object
      properties:
        verifiableCredential:
          $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
        frame:
          type: object
          description: A JSON-LD frame used for selective disclosure.
        options:
          $ref: "./components/DeriveCredentialOptions.yml#/components/schemas/DeriveCredentialOptions"
    DeriveCredentialResponse:
      $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
    ProvePresentationRequest:
      type: object
      properties:
        presentation:
          $ref: "./components/Presentation.yml#/components/schemas/Presentation"
        options:
          $ref: "./components/PresentCredentialOptions.yml#/components/schemas/PresentCredentialOptions"
    ProvePresentationResponse:
      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.",
                    },
                  ],
              },
            ],
        }
    NotifyPresentationAvailableResponse:
      type: object
      properties:
        query:
          type: object
          description: See https://w3c-ccg.github.io/vp-request-spec/#format
        domain:
          type: string
          description: See https://w3id.org/security#domain
        challenge:
          type: string
          description: See https://w3id.org/security#challenge
      example:
        {
          "query":
            [
              {
                "type": "QueryByFrame",
                "credentialQuery":
                  {
                    "frame":
                      {
                        "@context":
                          [
                              "https://www.w3.org/2018/credentials/v1",
                              "https://w3id.org/traceability/v1",
                              "https://w3id.org/bbs/v1",
                          ],
                        "type":
                          [
                              "VerifiableCredential",
                              "CommercialInvoiceCertificate",
                          ],
                        "credentialSubject":
                          {
                            "@explicit": true,
                            "type": ["CommercialInvoice"],
                            "purchaseDate": {},
                            "destinationCountry": {},
                          },
                      },
                  },
              },
            ],
          "domain": "jobs.example.com",
          "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
        }
    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"