Create a Web DID

Introduction

DIDs with a method of web are a type of DID where the DID Document is hosted on a domain in order to link it to that domain. For example, we’ve set up a DID Web using our own domain, which can be resolved at did:web:mattr.global.

Constraints

These DIDs rely inherently on the security of the website the DID Document is hosted on, we would generally only recommend the use of this DID on trusted known sites, like Government agencies and enterprises.

Create DID and DID Document

A DID with a DID method of web can be created as follows.

POST https://tenant.platform.mattr.global/v1/dids

Request

{
"method": "web",
"options": {
"domain": "organization.com"
}
}

The method is set to web in order to create a DID with a DID method of web.

The domain is the domain that will host the DID document.

In order to resolve the DID Document the domain will be prefixed with https:// and suffixed with /.well-known/did.json. This means that the DID Document in the example above should become available on https://organization.com/.well-known/did.json.

Response

{
"did": "did:web:organization.com",
"registrationStatus": "PROCESSING",
"localMetadata": {
"keys": [
{
"didDocumentKeyId": "did:web:organization.com#CfZMD88eoh",
"kmsKeyId": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
},
{
"didDocumentKeyId": "did:web:organization.com#9hvq54oWSa",
"kmsKeyId": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
}
],
"registered": 1600731355153,
"initialDidDocument": {
"@context": "https://w3.org/ns/did/v1",
"id": "did:web:organization.com",
"publicKey": [
{
"id": "did:web:organization.com#CfZMD88eoh",
"controller": "did:web:organization.com",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
}
],
"authentication": [
"did:web:organization.com#CfZMD88eoh"
],
"assertionMethod": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityDelegation": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityInvocation": [
"did:web:organization.com#CfZMD88eoh"
],
"keyAgreement": [
{
"id": "did:web:organization.com#6FstRAzj71",
"controller": "did:web:organization.com",
"type": "X25519KeyAgreementKey2019",
"publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
}
]
}
}
}

The returned initial DID Document then needs to be hosted so that it is accessible from the domain provided in the options.

Upload to website

Upload did.json to your domain in a folder called .well-known. It should contain the content obtained when creating the DID.

{
"@context": "https://w3.org/ns/did/v1",
"id": "did:web:organization.com",
"publicKey": [
{
"id": "did:web:organization.com#CfZMD88eoh",
"controller": "did:web:organization.com",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
}
],
"authentication": [
"did:web:organization.com#CfZMD88eoh"
],
"assertionMethod": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityDelegation": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityInvocation": [
"did:web:organization.com#CfZMD88eoh"
],
"keyAgreement": [
{
"id": "did:web:organization.com#6FstRAzj71",
"controller": "did:web:organization.com",
"type": "X25519KeyAgreementKey2019",
"publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
}
]
}

Resolve DID document

Download the DID Document from https://organization.com/.well-known/did.json to ensure it is available from the domain.

The tenant will be able to prove ownership of the keys associated with the did:web DID Document through the well-known endpoint, i.e. https://tenant.platform.mattr.global/.well-known/did-configuration, while the DID Document hosted on the domain links the DID to a domain.

GET https://tenant.platform.mattr.global/v1/dids/did:web:organization.com
{
"didDocument": {
"@context": "https://w3.org/ns/did/v1",
"id": "did:web:organization.com",
"publicKey": [
{
"id": "did:web:organization.com#CfZMD88eoh",
"controller": "did:web:organization.com",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
}
],
"authentication": [
"did:web:organization.com#CfZMD88eoh"
],
"assertionMethod": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityDelegation": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityInvocation": [
"did:web:organization.com#CfZMD88eoh"
],
"keyAgreement": [
{
"id": "did:web:organization.com#6FstRAzj71",
"controller": "did:web:organization.com",
"type": "X25519KeyAgreementKey2019",
"publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
}
]
},
"registrationStatus": "COMPLETED",
"localMetadata": {
"keys": [
{
"didDocumentKeyId": "did:web:organization.com#CfZMD88eoh",
"kmsKeyId": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
},
{
"didDocumentKeyId": "did:web:organization.com#9hvq54oWSa",
"kmsKeyId": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
}
],
"registered": 1600731355153,
"initialDidDocument": {
"@context": "https://w3.org/ns/did/v1",
"id": "did:web:organization.com",
"publicKey": [
{
"id": "did:web:organization.com#CfZMD88eoh",
"controller": "did:web:organization.com",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
}
],
"authentication": [
"did:web:organization.com#CfZMD88eoh"
],
"assertionMethod": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityDelegation": [
"did:web:organization.com#CfZMD88eoh"
],
"capabilityInvocation": [
"did:web:organization.com#CfZMD88eoh"
],
"keyAgreement": [
{
"id": "did:web:organization.com#6FstRAzj71",
"controller": "did:web:organization.com",
"type": "X25519KeyAgreementKey2019",
"publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
}
]
}
}
}

When the DID Document is not available for download from the domain, the Registration Status of the DID is PROCESSING. Once the DID Document can be downloaded from the domain, the Registration Status will be COMPLETED.