openapi: 3.0.0
info:
  version: 0.0.3-unstable
  title: VC Issuer 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-api
paths:
  /credentials/issue:
    post:
      summary: Issues a credential and returns it in the response body.
      tags:
        - credentialsIssue
      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/VerifiableCredential'
        '400':
          description: invalid input!
        '500':
          description: error!
  /credentials/{id}:
    get:
      summary: Gets a credential or verifiable credential by ID
      tags:
        - credentialsIssue
      operationId: getCredential
      parameters:
        - name: id
          in: path
          required: true
          schema:
            anyOf:
              - type: string
                pattern: "[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}"
              - type: string
                pattern: z[1-9A-HJ-NP-Za-km-z]{21,22}
              - type: string
                pattern: u[a-zA-Z0-9_-]{22,23}
              - type: string
                pattern: ^[A-Fa-f0-9]{24,128}$
          example:
            - f37e5114-8b4a-11ec-b32e-fbd62b9502c1
            - z4Z1T4HdLdfXCFAhdhzdCqm
            - u7m8_ybOArX-EWeADqWCsIw
            - 507f191e810c19729de860ea
            - >-
              4e59775105ee7a42696a6420e39eb3cf2512a04abf88e16696451cab59e25cdc1b0f0aa512f55dc009d38951b9c49e673e3f9f7669821f77733599b7fd72b15f
      responses:
        '200':
          description: Credential retrieved!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiableCredential'
        '400':
          description: invalid input!
        '500':
          description: error!
  /credentials/status:
    post:
      summary: Updates the status of an issued credential
      tags:
        - credentialsStatus
      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
components:
  schemas:
    IssueCredentialRequest:
      type: object
      properties:
        credential:
          $ref: '#/components/schemas/Credential'
        options:
          $ref: '#/components/schemas/IssueCredentialOptions'
    IssueCredentialResponse:
      $ref: '#/components/schemas/VerifiableCredential'
    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'
    Issuer:
      type: object
      oneOf:
        - type: string
        - type: object
          properties:
            id:
              type: string
      description: A JSON-LD Verifiable Credential Issuer.
      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:
          type: object
          discriminator:
            propertyName: issuer
            mapping:
              issuer: '#/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
    IssueCredentialOptions:
      type: object
      additionalProperties: false
      description: Options for specifying how the LinkedDataProof is created.
      properties:
        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:
        created: '2020-04-02T18:48:36Z'
        credentialStatus:
          type: RevocationList2020Status
    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.
        challenge:
          type: string
          description: >-
            A value chosen by the verifier to mitigate authentication proof
            replay attacks.
        domain:
          type: string
          description: The domain of the proof to restrict its use to a particular target.
        nonce:
          type: string
          description: >-
            A value chosen by the creator of a proof to randomize proof values
            for privacy purposes.
        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.
        proofValue:
          type: string
          description: Value of the Linked Data proof.
      example:
        type: Ed25519Signature2018
        created: '2020-04-02T18:28:08Z'
        verificationMethod: did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN
        proofPurpose: assertionMethod
        jws: >-
          eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA
    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