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

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

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

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

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

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

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

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

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

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"
}