Key management

Creating your JsonDIDKey

For End-2-End and Hybrid encryption, your VASP needs a dedicated DIDKey which is a public-private keypair. You can create a new keypair using the @notabene/cli and then publish it to the Notabene directory under the pii_didkey field. This allows other VASPs retrieve your public key and encrypt PII data to you:

  1. Installing the CLI:
npm i -g @notabene/cli
  1. Generate JsonDIDkey
notabene keys:create

The response will contain the Ed25519 key and metadata, which can be passed to the Notabene SDK when creating transactions to encrypt the PII:

did:             did:key:z6MkgZt2NgcKkhQFBoEAfYpfpswxSVXuT6RC29McxY9PvQGw
controllerKeyId: 1f698a52603efe1f8465a9ab826935a1cc51631c61a70f3f28559d6f77c98ec0
    type:          Ed25519
    kid:           1f698a52603efe1f8465a9ab826935a1cc51631c61a70f3f28559d6f77c98ec0
    publicKeyHex:  1f698a52603efe1f8465a9ab826935a1cc51631c61a70f3f28559d6f77c98ec0
        - Ed25519
        - EdDSA
    kms:           local
    privateKeyHex: d819d82d6cd458e6a74f0ff2ce200191ca524beda51ba95fe8be924fa4355cf21f698a52603efe1f8465a9ab826935a1cc51631c61a70f3f28559d6f77c98ec0
  (empty array)
provider:        did:key

Adding the public key to the Notabene network VASP profile

curl --location '{{baseURL}}/tf/vasps/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{ "did": "{{your_vasp_did}}",
    "fields": [
            "fieldName": "pii_didkey",
            "values": [
                    "value": "did:key:z6MkgZt2NgcKkhQFBoEAfYpfpswxSVXuT6RC29McxY9PvQGw"
const { Notabene } = require("@notabene/nodejs");

const client = new Notabene({
    authURL: '',
    baseURL: "",
    audience: "",
    clientId: "xxxxxxx",
    baseURLPII: "",
    audiencePII: "",

const pii_didkey = "did:key:z6MkjwpTikNZkpfop2ebcbPfsxi786ftTr9nGBD3XKKHZ2S"

const vaspDID = "did:ethr:0xd4bd902ec78578f33a20ff601504d2ab324cfab9"

// upload did:key to your VASP on the Notabene directory
const fields = [
    fieldName: 'pii_didkey',
    values: [
        value: pii_didkey,

const myfunc = async function () {
    const uploadKeys = await client.trustFramework.update(vaspDID, fields);
  myfunc().catch((err) => console.error(err));

Typically you will do this only once, and re-use the same keypair for a long time. If you believe your private key was compromised, you can rotate your keypair (ie. create a new one + publish it again). Data encrypted using a specific public key can only be decrypted with its private key, so don't throw away your old key(s) if you still have data of interest encrypted with those key(s).

Getting your counterparty's published key

Since the public keys of a VASP gets published in our directory, you can find it in the field called pii_didkey:

{{baseUrl}}/tf/simple/vasps/:vaspDID?fields=name,did, pii_didkey

    "name": "Notabene VASP SG",
    "did": "did:ethr:0xd4bd902ec78578f33a20ff601504d2ab324cfab9",
    "pii_didkey": "did:key:z6MkecCsDyGh4LdUSyhNdVX8E719o92HospPGETauaKpMmfr"

Getting your counterparty's escrow key

If your counterparty hasn't published their own public key, they will not be able to support an end-to-end encryption flow.

However, every VASP will have an escrow public key that has been generated by Notabene, so if you want to use a pseudo end-to-end encryption flow instead of the hosted/hybrid for these, you could use that key instead.

To get the key, you need to use our PII SDK and look up the key using the getEscrowDIDkeyfunction.

If a VASP doesn't have a published DID key and you encrypt the data using the escrow key, both the originator and beneficiary can see the PII in the UI by using the "decrypt" button.

const resp = await fetch('${beneficiaryVASPdid}' + new URLSearchParams({
			fields: "pii_didkey",
		}), options)
		.catch(err => console.error(err));

	const published_key = await resp.json()
		counterparty_didkey = resp.pii_didkey
		const resp = await toolset.getEscrowDIDkey(beneficiaryVASPdid)
		counterparty_didkey = resp.did