openapi: 3.0.1
info:
  title: Well-known DIDs API
  description: >-
    The Well Known DIDs API allows you to link DIDs to domain names and verify
    them.
  contact:
    name: Sphereon
    url: https://sphereon.com
    email: dev@sphereon.com
  version: 0.1
tags:
  - name: Resources
    description: Retrieve Did Configuration Resources
  - name: Services
    description: Create and Verify Domain Link Service Endpoints
  - name: Signatures
    description: Sign Domain Linkage Credentials
paths:
  /well-known-did/credentials/{credentialHash}/signature:
    post:
      tags:
        - Signatures
      summary: Provide the proof to an unsigned Domain Linkage Credential
      operationId: addDomainLinkageCredentialProof
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/credentialHash'
      requestBody:
        $ref: '#/components/requestBodies/AddSignatureRequest'
      responses:
        '200':
          description: >-
            A Domain Linkage Credential Response containing a signed Domain
            Linkage Credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedDomainLinkageCredentialReponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The credential was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Signatures
      summary: Update the proof for a Domain Linkage Credential
      operationId: updateDomainLinkageCredentialProof
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/credentialHash'
      requestBody:
        $ref: '#/components/requestBodies/UpdateSignatureRequest'
      responses:
        '200':
          description: >-
            A Domain Linkage Credential Response containing a signed Domain
            Linkage Credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedDomainLinkageCredentialReponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The credential was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Signatures
      summary: Delete the proof from a Domain Linkage Credential
      operationId: deleteDomainLinkageCredentialProof
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/credentialHash'
      responses:
        '200':
          description: Signature deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The credential was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /well-known-did/dids/{did}:
    get:
      tags:
        - Resources
      summary: Lists all published DID Configuration Resources associated with a DID
      operationId: getConfigurationResourcesByDid
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/did'
        - $ref: '#/components/parameters/originType'
        - $ref: '#/components/parameters/verificationChecks'
      responses:
        '200':
          description: >-
            A DID Configuration Resources Response containing an array with one
            or more DID Configuration Resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DidConfigurationResourcesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The DID was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /well-known-did/dids/{did}/services:
    post:
      tags:
        - Services
      summary: Creates a new Linked Domains Service Endpoint for the current DID
      operationId: createLinkedDomainsServiceEndpoint
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/did'
      requestBody:
        $ref: '#/components/requestBodies/CreateLinkedDomainsServiceEndpointRequest'
      responses:
        '202':
          description: >-
            A Domain Linkage Credentials Response containing an array with one
            or more Domain Linkage Credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkedDomainsServiceEndpointReponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The DID Configuration Resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /well-known-did/dids/{did}/services/{serviceId}:
    get:
      tags:
        - Services
      summary: >-
        Lists all Domain Linkage Credentials associated with a DID and Linked
        Domain Service Id
      operationId: getDomainLinkageCredentialByServiceId
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/did'
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/originType'
        - $ref: '#/components/parameters/verificationChecks'
      responses:
        '200':
          description: >-
            A Domain Linkage Credentials Response containing an array with one
            or more Domain Linkage Credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLinkedDomainsServiceEndpointReponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The DID or service was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Services
      summary: Updates a Linked Domain Service Endpoint for the current DID
      operationId: updateLinkedDomainServiceEndpoint
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/did'
        - $ref: '#/components/parameters/serviceId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateLinkedDomainServiceEndpointRequest'
      responses:
        '202':
          description: >-
            A Domain Linkage Credentials Response containing an array with one
            or more Domain Linkage Credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkedDomainsServiceEndpointReponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The DID or service was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Services
      summary: Deletes a Linked Domain Service Endpoint for the current DID
      operationId: deleteLinkedDomainServiceEndpoint
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/did'
        - $ref: '#/components/parameters/serviceId'
      responses:
        '202':
          description: Service deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The DID or service was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /well-known-did/origins/{origin}:
    get:
      tags:
        - Resources
      summary: Get a DID Configuration Resource associated with a domain
      operationId: getConfigResourceByDomain
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/origin'
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/verificationChecks'
      responses:
        '200':
          description: >-
            A DID Configuration Resource Response associated with the given
            domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DidConfigurationResourceResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The origin was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    UpdateLinkedDomainServiceEndpoint:
      required:
        - origins
      type: object
      properties:
        origins:
          type: array
          items:
            type: string
            description: The origin of a URL
          example:
            - https://example1.com
            - https://example2.com
    CredentialSubject:
      required:
        - id
        - origin
      type: object
      properties:
        id:
          type: string
          description: The id of the credential subject
          example: did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM
        origin:
          type: string
          description: The origin of a URL
          example: https://example.com
    CredentialProof:
      required:
        - type
        - created
        - proofPurpose
        - verificationMethod
      type: object
      properties:
        type:
          type: string
          description: The type of the proof
          example: Ed25519Signature2018
        created:
          type: string
          description: The date of when the proof was created
          format: date-time
          example: '2022-08-29T17:32:28Z'
        proofPurpose:
          type: string
          description: The purpose of the proof
          example: assertionMethod
        verificationMethod:
          type: string
          description: The verification method
          example: >-
            did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM
        challenge:
          type: string
          description: The challange used for verification
          example: 1f44d55f-f161-4938-a659-f8026467f126
        domain:
          type: string
          description: The domain
          example: 4jt78h47fh47
        proofValue:
          type: string
          description: The proof value
          example: >-
            z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz
        jws:
          type: string
          description: The JSON Web Signature
          example: eyJhbGciOiJFZERTQSIsImI2NC...
        nonce:
          type: string
          description: The nonce
          example: 660!6345FSer
        requiredRevealStatements:
          type: array
          items:
            type: string
            description: The required reveal statement
          example:
            - '1'
            - '2'
    CreateLinkedDomainServiceEndpoint:
      required:
        - origins
      type: object
      properties:
        origins:
          type: array
          items:
            type: string
            description: The origin of a URL
          example:
            - https://example1.com
            - https://example2.com
        serviceId:
          type: string
          description: The id of a Linked Domains Service Endpoint
          example: c3546e67-c8d8-45f7-a575-28b05fcd280b
    DomainLinkageCredential:
      required:
        - '@context'
        - issuer
        - credentialSubject
        - issuanceDate
        - expirationDate
      type: object
      properties:
        '@context':
          items:
            type: string
            description: The contexts of the credential
          example:
            - https://www.w3.org/2018/credentials/v1
            - https://identity.foundation/.well-known/did-configuration/v1
        issuer:
          type: string
          description: The issuer of the credential
          example: did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM
        credentialSubject:
          $ref: '#/components/schemas/CredentialSubject'
        type:
          type: array
          items:
            type: string
            description: The credential type
          example:
            - VerifiableCredential
            - DomainLinkageCredential
        issuanceDate:
          type: string
          description: The date of when the credential was issued
          format: date-time
          example: '2022-08-29T17:32:28Z'
        expirationDate:
          type: string
          description: The date of when the credential will expire
          format: date-time
          example: '2028-07-21T17:32:28Z'
    SignedDomainLinkageCredential:
      oneOf:
        - $ref: '#/components/schemas/SignedJsonldDomainLinkageCredential'
        - type: string
          example: eyJhbGci...
    SignedJsonldDomainLinkageCredential:
      required:
        - '@context'
        - issuer
        - credentialSubject
        - issuanceDate
        - expirationDate
        - proof
      allOf:
        - $ref: '#/components/schemas/DomainLinkageCredential'
        - type: object
          properties:
            proof:
              $ref: '#/components/schemas/CredentialProof'
    SignedDomainLinkageCredentialReponse:
      required:
        - credential
      type: object
      properties:
        credential:
          $ref: '#/components/schemas/SignedDomainLinkageCredential'
    LinkedDomainsServiceEndpointReponse:
      required:
        - didRelation
        - credentials
      type: object
      properties:
        didRelation:
          $ref: '#/components/schemas/DidRelation'
        credentials:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/SignedDomainLinkageCredential'
              - $ref: '#/components/schemas/DomainLinkageCredential'
    GetLinkedDomainsServiceEndpointReponse:
      required:
        - didRelation
        - credentials
      type: object
      properties:
        didRelation:
          $ref: '#/components/schemas/DidRelation'
        credentials:
          type: array
          items:
            type: object
            properties:
              credential:
                oneOf:
                  - $ref: '#/components/schemas/SignedDomainLinkageCredential'
                  - $ref: '#/components/schemas/DomainLinkageCredential'
                example: eyJhbGciOiJFZERTQSIsImI2NC...
              verification:
                $ref: '#/components/schemas/VerificationResults'
    DidConfigurationResourcesResponse:
      required:
        - didConfigurationResources
      type: object
      properties:
        didConfigurationResources:
          type: array
          items:
            $ref: '#/components/schemas/DidConfigurationResourceResponse'
    DidConfigurationResourceResponse:
      required:
        - origin
        - didConfigurationResource
      type: object
      properties:
        origin:
          type: string
          description: The origin of a URL
          example: https://example.com
        didConfigurationResource:
          $ref: '#/components/schemas/DidConfigurationResource'
        verification:
          $ref: '#/components/schemas/VerificationResults'
    DidConfigurationResource:
      required:
        - '@context'
        - linked_dids
      type: object
      properties:
        '@context':
          type: string
          description: The context of the DID Configuration Resource
          example: https://identity.foundation/.well-known/did-configuration/v1
        linked_dids:
          type: array
          description: >-
            The list of one or more Domain Linkage Credentials associated with
            an origin
          items:
            $ref: '#/components/schemas/SignedDomainLinkageCredential'
    VerificationChecks:
      type: string
      description: Verification checks able to be executed during verification
      example: STATUS
      enum:
        - ALL
        - STATUS
        - REVOCATION
        - SIGNATURE
    OriginType:
      type: string
      description: >-
        Types that can be set to either check a published external source using
        the origin URL, or from data stored in the VDX database
      example: SOURCE
      enum:
        - SOURCE
        - VDX
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: The error
          example: Internal Server Error
        path:
          type: string
          description: The REST endpoint path
          example: /signatures/create
        requestId:
          type: string
          description: The Unique Request Id
          example: 38fd064b
        status:
          type: integer
          description: The HTTP status code
          example: 500
        timestamp:
          type: string
          description: The timestamp of the error
          format: date-time
          example: '2022-06-11T22:53:40.276Z'
      description: The response returned in case of errors
    DidRelation:
      required:
        - serviceId
        - did
        - origins
      type: object
      properties:
        serviceId:
          type: string
          description: The id of a Linked Domains Service Endpoint
          example: c3546e67-c8d8-45f7-a575-28b05fcd280b
        did:
          type: string
          description: The DID identifier
          example: did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM
        origins:
          type: array
          items:
            description: The origin of a URL
            type: string
          example:
            - https://example1.com
            - https://example2.com
    VerificationStatus:
      type: string
      description: Verification status
      example: VALID
      enum:
        - VALID
        - INVALID
    VerificationResult:
      type: object
      properties:
        check:
          $ref: '#/components/schemas/VerificationChecks'
        status:
          $ref: '#/components/schemas/VerificationStatus'
        errors:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
    VerificationResults:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/VerificationStatus'
        verifications:
          type: array
          items:
            $ref: '#/components/schemas/VerificationResult'
  parameters:
    credentialHash:
      name: credentialHash
      description: The hash of a domain linkage credential
      in: path
      required: true
      schema:
        type: string
    did:
      name: did
      description: The DID identifier
      in: path
      required: true
      schema:
        type: string
    origin:
      name: origin
      description: The origin of a URL
      in: path
      required: true
      schema:
        type: string
    originType:
      name: originType
      description: >-
        The origin type to check. This is either a published external source
        which does not have to be part of VDX, or data in VDX itself
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/OriginType'
    verificationChecks:
      name: checks
      description: The verification checks able to be executed during verification
      in: query
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/VerificationChecks'
    serviceId:
      name: serviceId
      description: The id of a Linked Domains Service Endpoint
      in: path
      required: true
      schema:
        type: string
  requestBodies:
    CreateLinkedDomainsServiceEndpointRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateLinkedDomainServiceEndpoint'
      required: true
    UpdateLinkedDomainServiceEndpointRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateLinkedDomainServiceEndpoint'
      required: true
    AddSignatureRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CredentialProof'
      required: true
    UpdateSignatureRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CredentialProof'
      required: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT