Guides
GuidesReleasesPostmanRecipesAPI Reference

DIDdocs explained

Summary:

Retreive your DIDdoc from our server, we create one once your entity is created.

This DIDdoc contains the public keys and service url, allowing decentralized entities to identify each other, authenticate messages, establish encrypted channels, and send information securely via the provided service endpoint.

Update this DIDdoc with your #PII keys to receive and send end to end encrypted travel rule messages containing PII.

Host the DIDdoc on your own domain or set up a redirect to the default one at Notabene - note that this only works for hosted encryption.

Recap for webDIDs and DIDdoc hosting

You will, when your company entity is created in the Notabene Network, be assigned your webDID: The Web DID specification specifies the following structure for DIDs:

did:web:{your domain}

Which will resolve to https://{your domain}/.well-known/did.json

There is an optional path specification that allows multiple DIDs to be associated with the same root domain:

did:web:{domain}:{optional-path}

Which resolves to https://{domain}/{optional-path}/did.json. Note that wedrop the .well-known with optional paths as per the spec

Essentially it allows you to have multiple web dids, one for each of your entities, if and where applicable. The json DIDdoc is then hosted in your domain, in line with the webDID:

This can be extended to multiple entities in the same jurisdiction or country.

To enable transfer counterparties to encrypt messages to you, you first need to get your DID document. In a Travel Rule, Transaction Authorization and counterparty trust context, this DIDDoc allows decentralized entities to identify each other, authenticate messages, establish encrypted channels, and send information securely via the provided service endpoint. More specifically, this DIDdoc is used to encrypt messages by you, the Notabene platform, your counterparties to you, and to verify messages are signed by your entity, and to verify counterparty signatures, and needs to be hosted in your domain, for example: https://{domain}/us/did.json

In the DIDdoc you specify your public keys that can be used to:

  • send encrypted data to you (your service url)
  • validate messaged are coming from you by validating your signature

Furthermore you specify the “service” and its type and endpoint. The endpoint usually is the DIDComm endpoint on the Notabene Node where your Entity is onboarded to.

To enable Notabene to process the incoming and outgoing DIDComm messages, the Node will generate keys for your VASP and return these in the response when creating your Entity and can be retrieved by calling the Notabene API on GET {{url}}/entity/:entity/diddoc. Put your Entity webDID (e.g. did:web:Entity-A.com:us) in the path variable “:entityDID”.

  • example of Create Entity with keys in response:

    // create Entity via {{url}}/entity
{
    "domain": "vasps.id",
    "jurisdiction": "NO",
    "name": "Vasp.id Norway",
    "yearFounded": "2022",
    "website": "https://vasps.id/norway"
}

//response containing the public keys of your entity on the Notabene platform node
{"name":"Vasp.id Norway","legalName":null,"otherLegalName":null,"website":"https://vasps.id/norway","legalStructure":null,"yearFounded":"2022","incorporationCountry":null,"entityCategory":null,"entityStatus":null,"isRegulated":null,"regulatoryStatus":null,"supervisoryAuthority":null,"registrationLicenseId":null,"additionalInformation":null,"addressLine1":null,"addressLine2":null,"city":null,"country":null,"hqStreet":null,"hqNumber":null,"hqCity":null,"hqCountry":null,"hqPostcode":null,"hqRegion":null,"identificationType":null,"identificationNumber":null,"identificationCountryIssue":null,"identificationRegulatoryAuthority":null,"description":null,"logo":null,"immutableKeys":[],"externalVaspConfig":[],"domain":"vasps.id","jurisdiction":"NO","did":"did:web:vasps.id:no","sandbox":false,
"organizationId":"org_NCnQpewPeN1BZKmO",
"publicKeys":[
	{
				"id":"did:web:vasps.id:no#f04561d7cf575f70fa215ebf68d5602275bcb58db609920e5bcdb8d0b4db354e",
		"type":"X25519KeyAgreementKey2019",
		"controller":"did:web:vasps.id:no",
		"publicKeyHex":"f04561d7cf575f70fa215ebf68d5602275bcb58db609920e5bcdb8d0b4db354e",
		"publicKeyBase58":"HAvD9Xb3fKL6T2yDGfYeb7MEmYDmuFt3ghGHB1sLkwCH"},
	{
										"id":"did:web:vasps.id:no#ffb928f1d9cae66cac93eea038d6278e4fcf7bbac0bcb8a3857cf09cc456af9e",
		"type":"Ed25519VerificationKey2018",
		"controller":"did:web:vasps.id:no",
		"publicKeyHex":"ffb928f1d9cae66cac93eea038d6278e4fcf7bbac0bcb8a3857cf09cc456af9e",
		"publicKeyBase58":"JDEiinmhHVShmKq5STzzevH7ApZKdPanM8HioBEmki8m"
  },
	{
"id": "did:web:vasps.id:no#03e99b3207ae02bc01ff5f5164638b4e4a9aca1566db4000e4b7b52f3797884a1c#pii",
     "type": "EcdsaSecp256r1VerificationKey2019",
     "controller": "did:web:vasps.id:no",
     "publicKeyHex": "03e99b3207ae02bc01ff5f5164638b4e4a9aca1566db4000e4b7b52f3797884a1c"
        }]}

Essentially when you create your Entity, during the onboarding, your DIDDoc is generated automatically and is available on an endpoint on the node. The onboarding of a new Entity usually looks like:

  1. You create your Entity from the onboarding dashboard
  2. Depending on your needs, Notabene spins up a platform instance (called a ‘node’) for you, or you choose to onboard on a yet existing regional platform node
  3. You download the DIDDoc from the API or dashboard as part of onboarding
  4. You publish it to your domain - or use a redirect to our domain where we host the DIDDoc.
  5. (Optional) You add your own keys in addition to the node keys that are already in there.

  • An example DIDDoc with explainers inside:

    {
"@context": 
//This field defines the context for interpreting the DIDDoc, with links to standard schemas. It tells the system how to process specific properties and formats within the document, including security contexts that reference cryptographic key types (Ed25519 and X25519) commonly used for authentication and encryption.
[
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/ed25519-2018/v1",
"https://w3id.org/security/suites/x25519-2019/v1"
],
"id": "did:web:vasps.id:cryptoVASP",
//The id is the unique identifier for this DID. In this example, did:web:vasps.id:cryptoVASP signifies that this DID uses the "web" method and is hosted at the vasp's id domain with a specific identifier (cryptoVASP). This ID represents the entity associated with this DIDDoc.

"verificationMethod": 
//This section lists the cryptographic keys linked to the DID, which can be used for **verifying digital signatures** and **establishing secure communication**. Each entry specifies:
//*id*: A unique identifier for the verification method.
//*type*: The type of cryptographic key (e.g., Ed25519VerificationKey2018 for signing, X25519KeyAgreementKey2019 for DIDcomm message encryption and EcdsaSecp256r1VerificationKey2019 for PII encryption).
//*controller*: Indicates the DID this key is associated with.
//*publicKeyBase58*: The public key, encoded in Base58 format, used for signing or encryption. The keys listed here are like tools available to the DID. They tell you what kind of cryptographic operations this DID can perform, such as signing messages (for authentication) or establishing secure connections (for encryption).
[{
"id": "did:web:vasps.id:cryptoVASP#0e5ae2c0d1eee1be69757d18dc7a07c57d97be52ca7e26599ad89a7adb07c702",
"type": "Ed25519VerificationKey2018",
"controller": "did:web:vasps.id:cryptoVASP",
"publicKeyBase58": "y365f2VZQwV4qg7GPHvBswxBRE2e6P5HSts3pwysTsw"
},
{
"id": "did:web:vasps.id:cryptoVASP#12bbe6162ff25a8c85cf44ee730b6a8f48ac49285a1c8ea30622c0c80014b422",
"type": "X25519KeyAgreementKey2019",
"controller": "did:web:vasps.id:cryptoVASP",
"publicKeyBase58": "2G8WzpvzUTnX2GGPpf57hhzHh1Kwouxzb2oFU11sVeqF"
},
{
"id": "did:web:vasps.id:cryptoVASP#12bbe6162ff25a8c85cf44ee730b6a8f48ac49285a1c8ea30622c0c80014b555#pii",
"type": "EcdsaSecp256r1VerificationKey2019",
"controller": "did:web:vasps.id:cryptoVASP",
"publicKeyHex": "03e99b3207ae02bc01ff5f5164638b4e4a9aca1566db4000e4b7b52f3797884a1c"
}],
"authentication":
//This field points to keys in the verificationMethod (see above) that can be used to authenticate the entity controlling this DID. Here, did:web:vasps.id:cryptoVASP#0e5ae... is referenced for authentication, meaning it can authenticate messages or transactions related to this DID. To clarify, authentication is simply pointing to a key that’s already defined in verificationMethod, so it’s not creating anything new — it’s just giving those keys a specific role.
[ "did:web:vasps.id:cryptoVASP#0e5ae2c0d1eee1be69757d18dc7a07c57d97be52ca7e26599ad89a7adb07c702"
],
"assertionMethod": 
//This field designates keys for asserting claims, allowing this DID to validate claims made by the controller (e.g., issuing verifiable credentials). It references the same key as the authentication field in this case (the verification key).
[ "did:web:vasps.id:cryptoVASP#0e5ae2c0d1eee1be69757d18dc7a07c57d97be52ca7e26599ad89a7adb07c702"
],
"keyAgreement": 
//Keys listed here facilitate secure communication via encryption, allowing other parties to establish encrypted sessions. Both the Ed25519 and X25519 keys from verificationMethod are referenced for key agreement (we use the X25519 key but they are interchangeable), enabling secure Travel Rule message exchanges.
[
"did:web:vasps.id:cryptoVASP#0e5ae2c0d1eee1be69757d18dc7a07c57d97be52ca7e26599ad89a7adb07c702", "did:web:vasps.id:cryptoVASP#12bbe6162ff25a8c85cf44ee730b6a8f48ac49285a1c8ea30622c0c80014b422",
"did:web:vasps.id:cryptoVASP#12bbe6162ff25a8c85cf44ee730b6a8f48ac49285a1c8ea30622c0c80014b555#pii"
],
"service": 
//The service section provides endpoint information, specifying services associated with this DID. Here:
//*id*: A unique identifier for the service endpoint.
//*type*: Defines the type of service; DIDCommMessaging is typically used for DID-based messaging protocols.
//*serviceEndpoint*: The endpoint’s URL, where messages for this DID can be sent (we will provide you with the Notabene Node endpoint).
[{
"id": "did:web:vasps.id:cryptoVASP#vasp",
"type": "DIDCommMessaging",
"serviceEndpoint": "http://localhost:3000/didcomm"
}]}

When an Agent initiates a transfer in which you are listed or discovered as one of the Transfer participants, that Agent’s Node will find your DIDdoc via your webDID and send the DIDComm Transfer message to your Service endpoint, which in fact is the API of the (Notabene) Node you are onboarded on.

Your Notabene Platform node, when receiving such a Transfer message, will in return validate the sender’s DIDDoc and signature. It will then, if possible, decrypt using your private key and process the Transfer. Note: when you choose for full end to end encryption we cannot decrypt PII on your behalf.

Updated about 3 hours ago

What’s Next

Did this page help you?