Well-known DID - OpenAPI

Please note that if you are reading this line, it means the final documentation is not ready yet. Release of the full documentation is scheduled for the end of Q3 of 2023.

OpenAPI spec

• Resources
  • getLists all published DID Configuration Resources associated with a DID
  • getGet a DID Configuration Resource associated with a domain
• Services
  • postCreates a new Linked Domains Service Endpoint for the current DID
  • getLists all Domain Linkage Credentials associated with a DID and Linked Domain Service Id
  • putUpdates a Linked Domain Service Endpoint for the current DID
  • delDeletes a Linked Domain Service Endpoint for the current DID
• Signatures
  • postProvide the proof to an unsigned Domain Linkage Credential
  • putUpdate the proof for a Domain Linkage Credential
  • delDelete the proof from a Domain Linkage Credential

Documentation Powered by Redocly

Well-known DIDs API (0.1)

Download OpenAPI specification:Download

Sphereon: dev@sphereon.com URL: https://sphereon.com

The Well Known DIDs API allows you to link DIDs to domain names and verify them.

Resources

Retrieve Did Configuration Resources

Lists all published DID Configuration Resources associated with a DID

Authorizations:

bearerAuth

path Parameters

did required

string The DID identifier

query Parameters

originType	string (OriginType) Enum: "SOURCE" "VDX" Example: originType=SOURCE 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
checks	Array of strings (VerificationChecks) Items Enum: "ALL" "STATUS" "REVOCATION" "SIGNATURE" Example: checks=STATUS The verification checks able to be executed during verification

Responses

https://docs.vdx.sphereon.com/well-known-did/dids/{did}

Response samples

• 200
• 401
• 404
• default

Content type

application/json

{

• "didConfigurationResources": [

  • {

    • "origin": "https://example.com",
    • "didConfigurationResource": {

      • "@context": "https://identity.foundation/.well-known/did-configuration/v1",
      • "linked_dids": [

        • {

          • "@context": [

            • "https://www.w3.org/2018/credentials/v1",
            • "https://identity.foundation/.well-known/did-configuration/v1"

            ],
          • "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
          • "credentialSubject": {

            • "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
            • "origin": "https://example.com"

            },
          • "type": [

            • "VerifiableCredential",
            • "DomainLinkageCredential"

            ],
          • "issuanceDate": "2022-08-29T17:32:28Z",
          • "expirationDate": "2028-07-21T17:32:28Z",
          • "proof": {

            • "type": "Ed25519Signature2018",
            • "created": "2022-08-29T17:32:28Z",
            • "proofPurpose": "assertionMethod",
            • "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
            • "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
            • "domain": "4jt78h47fh47",
            • "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
            • "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
            • "nonce": "660!6345FSer",
            • "requiredRevealStatements": [

              • "1",
              • "2"

              ]

            }

          }

        ]

      },
    • "verification": {

      • "status": "VALID",
      • "verifications": [

        • {

          • "check": "STATUS",
          • "status": "VALID",
          • "errors": [

            • "string"

            ],
          • "warnings": [

            • "string"

            ]

          }

        ]

      }

    }

  ]

}

Get a DID Configuration Resource associated with a domain

Authorizations:

bearerAuth

path Parameters

origin required	string The origin of a URL
serviceId required	string The id of a Linked Domains Service Endpoint

query Parameters

checks

Array of strings (VerificationChecks) Items Enum: "ALL" "STATUS" "REVOCATION" "SIGNATURE" Example: checks=STATUS The verification checks able to be executed during verification

Responses

https://docs.vdx.sphereon.com/well-known-did/origins/{origin}

Response samples

• 200
• 401
• 404
• default

Content type

application/json

{

• "origin": "https://example.com",
• "didConfigurationResource": {

  • "@context": "https://identity.foundation/.well-known/did-configuration/v1",
  • "linked_dids": [

    • {

      • "@context": [

        • "https://www.w3.org/2018/credentials/v1",
        • "https://identity.foundation/.well-known/did-configuration/v1"

        ],
      • "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
      • "credentialSubject": {

        • "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
        • "origin": "https://example.com"

        },
      • "type": [

        • "VerifiableCredential",
        • "DomainLinkageCredential"

        ],
      • "issuanceDate": "2022-08-29T17:32:28Z",
      • "expirationDate": "2028-07-21T17:32:28Z",
      • "proof": {

        • "type": "Ed25519Signature2018",
        • "created": "2022-08-29T17:32:28Z",
        • "proofPurpose": "assertionMethod",
        • "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
        • "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
        • "domain": "4jt78h47fh47",
        • "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
        • "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
        • "nonce": "660!6345FSer",
        • "requiredRevealStatements": [

          • "1",
          • "2"

          ]

        }

      }

    ]

  },
• "verification": {

  • "status": "VALID",
  • "verifications": [

    • {

      • "check": "STATUS",
      • "status": "VALID",
      • "errors": [

        • "string"

        ],
      • "warnings": [

        • "string"

        ]

      }

    ]

  }

}

Services

Create and Verify Domain Link Service Endpoints

Creates a new Linked Domains Service Endpoint for the current DID

Authorizations:

bearerAuth

path Parameters

did required

string The DID identifier

Request Body schema: application/json

origins required	Array of strings
serviceId	string The id of a Linked Domains Service Endpoint

Responses

https://docs.vdx.sphereon.com/well-known-did/dids/{did}/services

Request samples

• Payload

Content type

application/json

{

• "origins": [

  • "https://example1.com",
  • "https://example2.com"

  ],
• "serviceId": "c3546e67-c8d8-45f7-a575-28b05fcd280b"

}

Response samples

• 202
• 401
• 404
• default

Content type

application/json

{

• "didRelation": {

  • "serviceId": "c3546e67-c8d8-45f7-a575-28b05fcd280b",
  • "did": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
  • "origins": [

    • "https://example1.com",
    • "https://example2.com"

    ]

  },
• "credentials": [

  • {

    • "@context": [

      • "https://www.w3.org/2018/credentials/v1",
      • "https://identity.foundation/.well-known/did-configuration/v1"

      ],
    • "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
    • "credentialSubject": {

      • "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
      • "origin": "https://example.com"

      },
    • "type": [

      • "VerifiableCredential",
      • "DomainLinkageCredential"

      ],
    • "issuanceDate": "2022-08-29T17:32:28Z",
    • "expirationDate": "2028-07-21T17:32:28Z",
    • "proof": {

      • "type": "Ed25519Signature2018",
      • "created": "2022-08-29T17:32:28Z",
      • "proofPurpose": "assertionMethod",
      • "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
      • "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
      • "domain": "4jt78h47fh47",
      • "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
      • "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
      • "nonce": "660!6345FSer",
      • "requiredRevealStatements": [

        • "1",
        • "2"

        ]

      }

    }

  ]

}

Lists all Domain Linkage Credentials associated with a DID and Linked Domain Service Id

Authorizations:

bearerAuth

path Parameters

did required	string The DID identifier
serviceId required	string The id of a Linked Domains Service Endpoint

query Parameters

originType	string (OriginType) Enum: "SOURCE" "VDX" Example: originType=SOURCE 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
checks	Array of strings (VerificationChecks) Items Enum: "ALL" "STATUS" "REVOCATION" "SIGNATURE" Example: checks=STATUS The verification checks able to be executed during verification

Responses

https://docs.vdx.sphereon.com/well-known-did/dids/{did}/services/{serviceId}

Response samples

• 200
• 401
• 404
• default

Content type

application/json

{

• "didRelation": {

  • "serviceId": "c3546e67-c8d8-45f7-a575-28b05fcd280b",
  • "did": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
  • "origins": [

    • "https://example1.com",
    • "https://example2.com"

    ]

  },
• "credentials": [

  • {

    • "credential": "eyJhbGciOiJFZERTQSIsImI2NC...",
    • "verification": {

      • "status": "VALID",
      • "verifications": [

        • {

          • "check": "STATUS",
          • "status": "VALID",
          • "errors": [

            • "string"

            ],
          • "warnings": [

            • "string"

            ]

          }

        ]

      }

    }

  ]

}

Updates a Linked Domain Service Endpoint for the current DID

Authorizations:

bearerAuth

path Parameters

did required	string The DID identifier
serviceId required	string The id of a Linked Domains Service Endpoint

Request Body schema: application/json

origins required

Array of strings

Responses

https://docs.vdx.sphereon.com/well-known-did/dids/{did}/services/{serviceId}

Request samples

• Payload

Content type

application/json

{

• "origins": [

  • "https://example1.com",
  • "https://example2.com"

  ]

}

Response samples

• 202
• 401
• 404
• default

Content type

application/json

{

• "didRelation": {

  • "serviceId": "c3546e67-c8d8-45f7-a575-28b05fcd280b",
  • "did": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
  • "origins": [

    • "https://example1.com",
    • "https://example2.com"

    ]

  },
• "credentials": [

  • {

    • "@context": [

      • "https://www.w3.org/2018/credentials/v1",
      • "https://identity.foundation/.well-known/did-configuration/v1"

      ],
    • "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
    • "credentialSubject": {

      • "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
      • "origin": "https://example.com"

      },
    • "type": [

      • "VerifiableCredential",
      • "DomainLinkageCredential"

      ],
    • "issuanceDate": "2022-08-29T17:32:28Z",
    • "expirationDate": "2028-07-21T17:32:28Z",
    • "proof": {

      • "type": "Ed25519Signature2018",
      • "created": "2022-08-29T17:32:28Z",
      • "proofPurpose": "assertionMethod",
      • "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
      • "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
      • "domain": "4jt78h47fh47",
      • "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
      • "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
      • "nonce": "660!6345FSer",
      • "requiredRevealStatements": [

        • "1",
        • "2"

        ]

      }

    }

  ]

}

Deletes a Linked Domain Service Endpoint for the current DID

Authorizations:

bearerAuth

path Parameters

did required	string The DID identifier
serviceId required	string The id of a Linked Domains Service Endpoint

Responses

https://docs.vdx.sphereon.com/well-known-did/dids/{did}/services/{serviceId}

Response samples

• 401
• 404
• default

Content type

application/json

{

• "error": "Internal Server Error",
• "path": "/signatures/create",
• "requestId": "38fd064b",
• "status": 500,
• "timestamp": "2022-06-11T22:53:40.276Z"

}

Signatures

Sign Domain Linkage Credentials

Provide the proof to an unsigned Domain Linkage Credential

Authorizations:

bearerAuth

path Parameters

credentialHash required

string The hash of a domain linkage credential

Request Body schema: application/json

type required	string The type of the proof
created required	string <date-time> The date of when the proof was created
proofPurpose required	string The purpose of the proof
verificationMethod required	string The verification method
challenge	string The challange used for verification
domain	string The domain
proofValue	string The proof value
jws	string The JSON Web Signature
nonce	string The nonce
requiredRevealStatements	Array of strings

Responses

https://docs.vdx.sphereon.com/well-known-did/credentials/{credentialHash}/signature

Request samples

• Payload

Content type

application/json

{

• "type": "Ed25519Signature2018",
• "created": "2022-08-29T17:32:28Z",
• "proofPurpose": "assertionMethod",
• "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
• "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
• "domain": "4jt78h47fh47",
• "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
• "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
• "nonce": "660!6345FSer",
• "requiredRevealStatements": [

  • "1",
  • "2"

  ]

}

Response samples

• 200
• 401
• 404
• default

Content type

application/json

{

• "credential": {

  • "@context": [

    • "https://www.w3.org/2018/credentials/v1",
    • "https://identity.foundation/.well-known/did-configuration/v1"

    ],
  • "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
  • "credentialSubject": {

    • "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
    • "origin": "https://example.com"

    },
  • "type": [

    • "VerifiableCredential",
    • "DomainLinkageCredential"

    ],
  • "issuanceDate": "2022-08-29T17:32:28Z",
  • "expirationDate": "2028-07-21T17:32:28Z",
  • "proof": {

    • "type": "Ed25519Signature2018",
    • "created": "2022-08-29T17:32:28Z",
    • "proofPurpose": "assertionMethod",
    • "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
    • "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
    • "domain": "4jt78h47fh47",
    • "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
    • "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
    • "nonce": "660!6345FSer",
    • "requiredRevealStatements": [

      • "1",
      • "2"

      ]

    }

  }

}

Update the proof for a Domain Linkage Credential

Authorizations:

bearerAuth

path Parameters

credentialHash required

string The hash of a domain linkage credential

Request Body schema: application/json

type required	string The type of the proof
created required	string <date-time> The date of when the proof was created
proofPurpose required	string The purpose of the proof
verificationMethod required	string The verification method
challenge	string The challange used for verification
domain	string The domain
proofValue	string The proof value
jws	string The JSON Web Signature
nonce	string The nonce
requiredRevealStatements	Array of strings

Responses

https://docs.vdx.sphereon.com/well-known-did/credentials/{credentialHash}/signature

Request samples

• Payload

Content type

application/json

{

• "type": "Ed25519Signature2018",
• "created": "2022-08-29T17:32:28Z",
• "proofPurpose": "assertionMethod",
• "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
• "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
• "domain": "4jt78h47fh47",
• "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
• "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
• "nonce": "660!6345FSer",
• "requiredRevealStatements": [

  • "1",
  • "2"

  ]

}

Response samples

• 200
• 401
• 404
• default

Content type

application/json

{

• "credential": {

  • "@context": [

    • "https://www.w3.org/2018/credentials/v1",
    • "https://identity.foundation/.well-known/did-configuration/v1"

    ],
  • "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
  • "credentialSubject": {

    • "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
    • "origin": "https://example.com"

    },
  • "type": [

    • "VerifiableCredential",
    • "DomainLinkageCredential"

    ],
  • "issuanceDate": "2022-08-29T17:32:28Z",
  • "expirationDate": "2028-07-21T17:32:28Z",
  • "proof": {

    • "type": "Ed25519Signature2018",
    • "created": "2022-08-29T17:32:28Z",
    • "proofPurpose": "assertionMethod",
    • "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
    • "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
    • "domain": "4jt78h47fh47",
    • "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz",
    • "jws": "eyJhbGciOiJFZERTQSIsImI2NC...",
    • "nonce": "660!6345FSer",
    • "requiredRevealStatements": [

      • "1",
      • "2"

      ]

    }

  }

}

Delete the proof from a Domain Linkage Credential

Authorizations:

bearerAuth

path Parameters

credentialHash required

string The hash of a domain linkage credential

Responses

https://docs.vdx.sphereon.com/well-known-did/credentials/{credentialHash}/signature

Response samples

• 401
• 404
• default

Content type

application/json

{

• "error": "Internal Server Error",
• "path": "/signatures/create",
• "requestId": "38fd064b",
• "status": 500,
• "timestamp": "2022-06-11T22:53:40.276Z"

}