Host your DID document

Your DID document is the public part of your identity on the Notabene network. It holds your public keys and tells other institutions where to deliver Travel Rule messages to you. In production you publish it on your own domain, at the address your DID points to, while in sandbox Notabene publishes it and you have nothing to do.

1. Get your DID document (You, from the API). Notabene creates your DID document together with your account. Once your account is active, 1. Get your DID document shows how to read it.
2. Find where it must be hosted (https://{domain}/{jurisdiction}/did.json, From your DID). Your DID tells you where the document must be hosted, and 2. Find where it must be hosted gives the rule with examples.
3. Host a copy: Publish the file (You, on your web server). Save the document as did.json at that address, served over HTTPS as JSON. See 3. Publish it.
4. Host a copy: Add your own key (optional, You, for end-to-end encryption). To receive Travel Rule data that only you can decrypt, add your own public key to the copy, next to Notabene’s keys. See 3. Publish it.
5. Redirect: Redirect to Notabene (You, on your web server). Redirect that address to Notabene’s copy, which stays up to date by itself. See 3. Publish it.
6. Check that it is online (You). Open the address in a browser or with curl and check that it returns your DID document, as in 4. Check that it is online.

1. Get your DID document

Notabene creates your DID document together with your account. Once your account is active (step 4 of Create your account), read it through the API with an access token, as described in Authentication.

curl https://sandbox.notabene.id/api/v1/identity \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'const response = await fetch('https://sandbox.notabene.id/api/v1/identity', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
  },
});
const answer = response.status === 204 ? null : await response.json();import requests

response = requests.get(
    'https://sandbox.notabene.id/api/v1/identity',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
)
answer = None if response.status_code == 204 else response.json()

{
  "did": "did:web:example.com:pt",
  "document": {
    "@context": [
      "https://www.w3.org/ns/did/v1",
      "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "did:web:example.com:pt",
    "verificationMethod": [
      {
        "id": "did:web:example.com:pt#nb-signing",
        "type": "JsonWebKey2020",
        "controller": "did:web:example.com:pt",
        "publicKeyJwk": {
          "kty": "OKP",
          "crv": "Ed25519",
          "x": "Qm3P8a5DdOU1x9xKq0GZ4vFgk2Yc7Wbz2rNnT0sJmVw"
        }
      },
      {
        "id": "did:web:example.com:pt#nb-key-agreement",
        "type": "JsonWebKey2020",
        "controller": "did:web:example.com:pt",
        "publicKeyJwk": {
          "kty": "OKP",
          "crv": "X25519",
          "x": "hS9pQmV4c2tXbk1hY0w2ZlJ0eUJ3c0ZqNXpQa0h1dE0"
        }
      },
      {
        "id": "did:web:example.com:pt#nb-pii",
        "type": "JsonWebKey2020",
        "controller": "did:web:example.com:pt",
        "publicKeyJwk": {
          "kty": "EC",
          "crv": "P-256",
          "x": "QPd12KIDz9nFplcr_zn0aUHZlS5xeAxF1yBhevpPixU",
          "y": "eyqRi-hjnxxItYmZjWiHKvmJF3yMvCcz0T3lvVhZLXU"
        }
      }
    ],
    "authentication": [
      "did:web:example.com:pt#nb-signing"
    ],
    "assertionMethod": [
      "did:web:example.com:pt#nb-signing"
    ],
    "keyAgreement": [
      "did:web:example.com:pt#nb-key-agreement",
      "did:web:example.com:pt#nb-pii"
    ],
    "service": [
      {
        "id": "did:web:example.com:pt#didcomm",
        "type": "DIDCommMessaging",
        "serviceEndpoint": {
          "uri": "https://eu-a.notabene.id/didcomm",
          "accept": [
            "didcomm/v2"
          ],
          "routingKeys": []
        }
      }
    ]
  }
}

curl https://sandbox.notabene.id/api/v1/identity \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

const response = await fetch('https://sandbox.notabene.id/api/v1/identity', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
  },
});
const answer = response.status === 204 ? null : await response.json();

import requests

response = requests.get(
    'https://sandbox.notabene.id/api/v1/identity',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
)
answer = None if response.status_code == 204 else response.json()

{
  "did": "did:web:example.com:pt",
  "document": {
    "@context": [
      "https://www.w3.org/ns/did/v1",
      "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "did:web:example.com:pt",
    "verificationMethod": [
      {
        "id": "did:web:example.com:pt#nb-signing",
        "type": "JsonWebKey2020",
        "controller": "did:web:example.com:pt",
        "publicKeyJwk": {
          "kty": "OKP",
          "crv": "Ed25519",
          "x": "Qm3P8a5DdOU1x9xKq0GZ4vFgk2Yc7Wbz2rNnT0sJmVw"
        }
      },
      {
        "id": "did:web:example.com:pt#nb-key-agreement",
        "type": "JsonWebKey2020",
        "controller": "did:web:example.com:pt",
        "publicKeyJwk": {
          "kty": "OKP",
          "crv": "X25519",
          "x": "hS9pQmV4c2tXbk1hY0w2ZlJ0eUJ3c0ZqNXpQa0h1dE0"
        }
      },
      {
        "id": "did:web:example.com:pt#nb-pii",
        "type": "JsonWebKey2020",
        "controller": "did:web:example.com:pt",
        "publicKeyJwk": {
          "kty": "EC",
          "crv": "P-256",
          "x": "QPd12KIDz9nFplcr_zn0aUHZlS5xeAxF1yBhevpPixU",
          "y": "eyqRi-hjnxxItYmZjWiHKvmJF3yMvCcz0T3lvVhZLXU"
        }
      }
    ],
    "authentication": [
      "did:web:example.com:pt#nb-signing"
    ],
    "assertionMethod": [
      "did:web:example.com:pt#nb-signing"
    ],
    "keyAgreement": [
      "did:web:example.com:pt#nb-key-agreement",
      "did:web:example.com:pt#nb-pii"
    ],
    "service": [
      {
        "id": "did:web:example.com:pt#didcomm",
        "type": "DIDCommMessaging",
        "serviceEndpoint": {
          "uri": "https://eu-a.notabene.id/didcomm",
          "accept": [
            "didcomm/v2"
          ],
          "routingKeys": []
        }
      }
    ]
  }
}

Publish only the document object, because the response also holds your DID.

2. Find where it must be hosted

Hosting the document on your own domain is what lets counterparties trust the keys in it. Your DID names your domain, so a counterparty fetches the document from that domain over HTTPS, and only whoever controls the domain can publish a file there. Counterparties therefore know the keys belong to the institution behind the domain, and that a message signed with them comes from you. When the document does not answer at that address, they cannot check your signatures and do not accept your messages.

The address comes from your DID: each part after the domain becomes a folder, then did.json. It must be served over HTTPS on exactly that host, and example.com and www.example.com count as two different addresses.

3. Publish it

Either host a copy of the document at that address, or redirect the address to Notabene’s copy. A redirect is also set up on your domain, so either way your domain vouches for the document.

To receive personal data that only you can decrypt, add your own public key to your copy next to Notabene’s keys, as described in Encryption. Leave the keys already in it in place, including the PII key whose id ends in #nb-pii, because Notabene uses them for more than personal data. Give your own key the id #pii, as a P-256 key listed under keyAgreement.

4. Check that it is online

Open the address in a browser or with curl, and check that it returns your DID document with your DID as its id.

curl -sL https://example.com/pt/did.json

curl -sL https://example.com/pt/did.json

Most often the problem is a redirect from example.com to www.example.com, a login page or firewall in front of the file, or an HTML error page instead of JSON. If the document stops answering later, the dashboard Inbox shows the warning “Your DID doc is unreachable”.

What the document contains

Notabene generates the document for you, as in the response of step 1. Publish it as it is, unless you add your own key for end-to-end encryption.

To learn more about DID documents, see the W3C DID specification, and for how a DID is read from its domain, the did:web method specification.

In sandbox

Notabene publishes your sandbox DID document, so you do not need to do anything. To test end-to-end encryption in sandbox, download the document from the address your DID points to and add your own key to it, as in 3. Publish it. Then send the edited document to your Notabene Account Manager or [email protected], and Notabene publishes it in place of the one it generated.