vc-http-api.yml

openapi: 3.0.0
info:
  version: "0.0.2-unstable"
  title: VC HTTP 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-http-api
tags:
  - name: Issuer
    description: APIs for Issuers.
  - name: Verifier
    description: APIs for Verifiers.
  - name: Holder
    description: Optional APIs for Holders.
paths:
  /credentials/issue:
    post:
      tags:
        - Issuer
      summary: Issues a credential and returns it in the response body.
      operationId: issueCredential
      description: Issues a credential and returns it in the response body.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssueCredentialRequest"
        description: Parameters for issuing the credential.
      responses:
        "201":
          description: Credential successfully issued!
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueCredentialResponse"
        "400":
          description: invalid input!
        "500":
          description: error!
  /credentials/derive:
    post:
      tags:
        - Holder
      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
  /credentials/status:
    post:
      tags:
        - Issuer
      summary: Updates the status of an issued credential
      operationId: updateCredentialStatus
      description: Updates the status of an issued credential.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCredentialStatus"
        description: Parameters for updating the status of the issued credential.
      responses:
        "200":
          description: Credential status successfully updated
        "400":
          description: Bad Request
        "404":
          description: Credential not found
        "500":
          description: Internal Server Error
  /presentations/prove:
    post:
      tags:
        - Holder
      summary: Proves a presentation and returns it in the response body.
      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!
  /credentials/verify:
    post:
      tags:
        - Verifier
      summary: Verifies a verifiableCredential and returns a verificationResult in the response body.
      operationId: verifyCredential
      description: Verifies a verifiableCredential and returns a verificationResult in the response body.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyCredentialRequest"
        description: Parameters for verifying a verifiableCredential.
      responses:
        "200":
          description: Verifiable Credential successfully verified!
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifyCredentialResponse"
        "400":
          description: invalid input!
        "500":
          description: error!
  /presentations/verify:
    post:
      tags:
        - Verifier
      summary: Verifies a Presentation with or without proofs attached and returns a verificationResult in the response body.
      operationId: verifyPresentation
      description: Verifies a verifiablePresentation and returns a verificationResult in the response body.  Given the possibility of denial of service, buffer overflow, or other style attacks, an implementation is permitted to rate limit or restrict requests against this API endpoint to those requests that contain only a single credential with a 413 or 429 error code as appropriate.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/VerifyPresentationRequest"
                - $ref: "#/components/schemas/ProoflessVerifyPresentationRequest"
        description: Parameters for verifying a verifiablePresentation.
      responses:
        "200":
          description: Verifiable Presentation successfully verified!
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifyPresentationResponse"
        "400":
          description: Invalid or malformed input
        "413":
          description: Payload too large
        "429":
          description: Request rate limit exceeded.
        "500":
          description: Internal Server Error

components:
  schemas:
    UpdateCredentialStatus:
      type: object
      description: Request for updating the status of an issued credential.
      properties:
        credentialId:
          type: string
        credentialStatus:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              status:
                type: string
      example:
        {
          "credentialId": "urn:uuid:45a44711-e457-4fa8-9b89-69fe0287c86a",
          "credentialStatus":
            [{ "type": "RevocationList2020Status", "status": "0" }],
        }
    LinkedDataProof:
      type: object
      description: A JSON-LD Linked Data proof.
      properties:
        type:
          type: string
          description: Linked Data Signature Suite used to produce proof.
        created:
          type: string
          description: Date the proof was created.
        verificationMethod:
          type: string
          description: Verification Method used to verify proof.
        proofPurpose:
          type: string
          description: The purpose of the proof to be used with verificationMethod.
        jws:
          type: string
          description: Detached JSON Web Signature
      example:
        {
          "type": "Ed25519Signature2018",
          "created": "2020-04-02T18:28:08Z",
          "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
          "proofPurpose": "assertionMethod",
          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA",
        }
    IssueCredentialOptions:
      type: object
      additionalProperties: false
      description: Options for specifying how the LinkedDataProof is created.
      properties:
        verificationMethod:
          type: string
          description: The URI of the verificationMethod used for the proof. Default assertionMethod URI.
        proofPurpose:
          type: string
          description: The purpose of the proof. Default 'assertionMethod'.
        created:
          type: string
          description: The date and time of the proof (with a maximum accuracy in seconds). Default current system time.
        challenge:
          type: string
          description: A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2
        domain:
          type: string
          description: The intended domain of validity for the proof. For example website.example
        credentialStatus:
          type: object
          description: The method of credential status to issue the credential including. If omitted credential status will be included.
          properties:
            type:
              type: string
              description: The type of credential status to issue the credential with
      example:
        {
          "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
          "proofPurpose": "assertionMethod",
          "created": "2020-04-02T18:48:36Z",
          "domain": "revocation.example",
          "challenge": "d436f0c8-fbd9-4e48-bbb2-55fc5d0920a8",
          "credentialStatus": { "type": "RevocationList2020Status" },
        }
    PresentCredentialOptions:
      type: object
      additionalProperties: false
      description: Options for specifying how the LinkedDataProof is created.
      properties:
        verificationMethod:
          type: string
          description: The URI of the verificationMethod used for the proof. Default assertionMethod URI.
        proofPurpose:
          type: string
          description: The purpose of the proof. Default 'assertionMethod'.
        created:
          type: string
          description: The date and time of the proof (with a maximum accuracy in seconds). Default current system time.
        challenge:
          type: string
          description: A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2
        domain:
          type: string
          description: The intended domain of validity for the proof. For example website.example
      example:
        {
          "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
          "proofPurpose": "assertionMethod",
          "created": "2020-04-02T18:48:36Z",
          "domain": "example.com",
          "challenge": "d436f0c8-fbd9-4e48-bbb2-55fc5d0920a8",
        }
    DeriveCredentialOptions:
      type: object
      additionalProperties: false
      description: Options for specifying how the derived credential is created.
      properties:
        nonce:
          type: string
          description: An encoded nonce provided by the holder of the credential to be included into the LinkedDataProof.
      example:
        {
          "nonce": "lEixQKDQvRecCifKl789TQj+Ii6YWDLSwn3AxR0VpPJ1QV5htod/0VCchVf1zVM0y2E=",
        }
    VerifyOptions:
      type: object
      additionalProperties: false
      description: Options for specifying how the LinkedDataProof is created.
      properties:
        verificationMethod:
          type: string
          description: The URI of the verificationMethod used for the proof. Default assertionMethod URI.
        proofPurpose:
          type: string
          description: The purpose of the proof. Default 'assertionMethod'.
        created:
          type: string
          description: The date and time of the proof (with a maximum accuracy in seconds). Default current system time.
        challenge:
          type: string
          description: A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2
        domain:
          type: string
          description: The intended domain of validity for the proof. For example website.example
      example:
        {
          "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
          "proofPurpose": "assertionMethod",
          "created": "2020-04-02T18:48:36Z",
          "domain": "example.com",
          "challenge": "d436f0c8-fbd9-4e48-bbb2-55fc5d0920a8",
        }
    VerificationResult:
      type: object
      additionalProperties: false
      description: Object summarizing a verification
      properties:
        checks:
          type: array
          description: The checks performed
          items:
            type: string
        warnings:
          type: array
          description: Warnings
          items:
            type: string
        errors:
          type: array
          description: Errors
          items:
            type: string
      example: { "checks": ["proof"], "warnings": [], "errors": [] }
    Issuer:
      type: object
      description: A JSON-LD Verifiable Credential Issuer.
      oneOf:
        - type: string
        - type: object
          properties:
            id:
              type: string
      example:
        { "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd" }
    Credential:
      type: object
      description: A JSON-LD Verifiable Credential without a proof.
      properties:
        "@context":
          type: array
          description: The JSON-LD context of the credential.
          items:
            type: string
        "id":
          type: string
          description: The ID of the credential.
        "type":
          type: array
          description: The JSON-LD type of the credential.
          items:
            type: string
        "issuer":
          $ref: "#/components/schemas/Issuer"
        "issuanceDate":
          type: string
          description: The issuanceDate
        "expirationDate":
          type: string
          description: The expirationDate
        "credentialSubject":
          type: object
          description: The subject
      example:
        {
          "@context":
            [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1",
            ],
          "id": "http://example.gov/credentials/3732",
          "type": ["VerifiableCredential", "UniversityDegreeCredential"],
          "issuer": "did:example:123",
          "issuanceDate": "2020-03-16T22:37:26.544Z",
          "credentialSubject":
            {
              "id": "did:example:123",
              "degree":
                {
                  "type": "BachelorDegree",
                  "name": "Bachelor of Science and Arts",
                },
            },
        }
    VerifiableCredential:
      type: object
      description: A JSON-LD Verifiable Credential with a proof.
      allOf:
        - $ref: "#/components/schemas/Credential"
        - type: object
          properties:
            proof:
              $ref: "#/components/schemas/LinkedDataProof"
      example:
        {
          "@context":
            [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1",
            ],
          "id": "http://example.gov/credentials/3732",
          "type": ["VerifiableCredential", "UniversityDegreeCredential"],
          "issuer": "did:example:123",
          "issuanceDate": "2020-03-16T22:37:26.544Z",
          "credentialSubject":
            {
              "id": "did:example:123",
              "degree":
                {
                  "type": "BachelorDegree",
                  "name": "Bachelor of Science and Arts",
                },
            },
          "proof":
            {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA",
            },
        }
    Presentation:
      type: object
      description: A JSON-LD Verifiable Presentation without a proof.
      properties:
        "@context":
          type: array
          description: The JSON-LD context of the presentation.
          items:
            type: string
        "id":
          type: string
          description: The ID of the presentation.
        "type":
          type: array
          description: The JSON-LD type of the presentation.
          items:
            type: string
        "holder":
          type: object
          description: The holder - will be ignored if no proof is present since there is no proof of authority over the credentials
          nullable: true
        "verifiableCredential":
          type: array
          description: The Verifiable Credentials
          items:
            type: object
      example:
        {
          "@context":
            [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1",
            ],
          "holder": "did:example:123",
          "type": "VerifiablePresentation",
          "verifiableCredential":
            [
              "@context":
                [
                  "https://www.w3.org/2018/credentials/v1",
                  "https://www.w3.org/2018/credentials/examples/v1",
                ],
              "id": "http://example.gov/credentials/3732",
              "type": ["VerifiableCredential", "UniversityDegreeCredential"],
              "issuer": "did:example:123",
              "issuanceDate": "2020-03-16T22:37:26.544Z",
              "credentialSubject":
                {
                  "id": "did:example:123",
                  "degree":
                    {
                      "type": "BachelorDegree",
                      "name": "Bachelor of Science and Arts",
                    },
                },
              "proof":
                {
                  "type": "Ed25519Signature2018",
                  "created": "2020-04-02T18:28:08Z",
                  "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                  "proofPurpose": "assertionMethod",
                  "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA",
                },
            ],
        }
    VerifiablePresentation:
      type: object
      description: A JSON-LD Verifiable Presentation with a proof.
      allOf:
        - $ref: "#/components/schemas/Presentation"
        - type: object
          properties:
            proof:
              $ref: "#/components/schemas/LinkedDataProof"
      example:
        {
          "@context":
            [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1",
            ],
          "holder": "did:example:123",
          "type": "VerifiablePresentation",
          "verifiableCredential":
            [
              "@context":
                [
                  "https://www.w3.org/2018/credentials/v1",
                  "https://www.w3.org/2018/credentials/examples/v1",
                ],
              "id": "http://example.gov/credentials/3732",
              "type": ["VerifiableCredential", "UniversityDegreeCredential"],
              "issuer": "did:example:123",
              "issuanceDate": "2020-03-16T22:37:26.544Z",
              "credentialSubject":
                {
                  "id": "did:example:123",
                  "degree":
                    {
                      "type": "BachelorDegree",
                      "name": "Bachelor of Science and Arts",
                    },
                },
              "proof":
                {
                  "type": "Ed25519Signature2018",
                  "created": "2020-04-02T18:28:08Z",
                  "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                  "proofPurpose": "assertionMethod",
                  "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA",
                },
            ],
          "proof":
            {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA",
            },
        }
    IssueCredentialRequest:
      type: object
      properties:
        credential:
          $ref: "#/components/schemas/Credential"
        options:
          $ref: "#/components/schemas/IssueCredentialOptions"
    IssueCredentialResponse:
      $ref: "#/components/schemas/VerifiableCredential"
    DeriveCredentialRequest:
      type: object
      properties:
        verifiableCredential:
          $ref: "#/components/schemas/VerifiableCredential"
        frame:
          type: object
          description: A JSON-LD frame used for selective disclosure.
        options:
          $ref: "#/components/schemas/DeriveCredentialOptions"
    DeriveCredentialResponse:
      $ref: "#/components/schemas/VerifiableCredential"
    ProvePresentationRequest:
      type: object
      properties:
        presentation:
          $ref: "#/components/schemas/Presentation"
        options:
          $ref: "#/components/schemas/PresentCredentialOptions"
    ProvePresentationResponse:
      $ref: "#/components/schemas/VerifiablePresentation"
    VerifyCredentialRequest:
      type: object
      properties:
        verifiableCredential:
          $ref: "#/components/schemas/VerifiableCredential"
        options:
          $ref: "#/components/schemas/VerifyOptions"
    VerifyCredentialResponse:
      $ref: "#/components/schemas/VerificationResult"
    VerifyPresentationRequest:
      type: object
      properties:
        verifiablePresentation:
          $ref: "#/components/schemas/VerifiablePresentation"
        options:
          $ref: "#/components/schemas/VerifyOptions"
    ProoflessVerifyPresentationRequest:
      type: object
      properties:
        presentation:
          $ref: "#/components/schemas/Presentation"
    VerifyPresentationResponse:
      $ref: "#/components/schemas/VerificationResult"