GuidesPostman CollectionRecipesAPI Reference

The Notabene agent

Suggest Edits

The Notabene agent is a Docker container that enables a VASP to easily set up E2E and hybrid encryption.
You can get the Notabene agent from here

Usage

To use the Notabene Agent, follow these steps:

Clone the repository: 

git clone [email protected]:notabene/open-source/notabene-agent.git

https://gitlab.com/notabene/open-source/notabene-agent.git

Move into the right directory

cd notabene-agent

Build the Docker image:

   docker build -t notabene-agent .

Run the container, and make sure to customize the URLs api.notabene.id and pii.notabene.id if you are looking to use it in the production environment, and api.notabene.dev and pii.notabene.dev for the test environment

   docker run \
      -p 3000:8080 \
      -e PORT=8080 \
      -e CLIENT_ID=YourClientId \
      -e CLIENT_SECRET=YourClientSecret \
      -e AUTH_URL=https://auth.notabene.id \
      -e AUDIENCE=https://api.notabene.id \
      -e BASE_URL=https://api.notabene.id \
      -e AUDIENCE_PII=https://pii.notabene.id \
      -e BASEURL_PII=https://pii.notabene.id \
      -e KEYS='[{"vaspDID":"did:ethr:0x1111111","privateKeyHex":"987654321___123456789"}]' \
      notabene-agent

   // By default the Notabene Agent listens on port 3000. The -p option maps a host port to the container port.
   // The KEYS argument is optional, but required for Hybrid and E2E encryption flows.

  docker run \
      -p 3000:8080 \
      -e PORT=8080 \
      -e CLIENT_ID=YourClientId \
      -e CLIENT_SECRET=YourClientSecret \
      -e AUTH_URL=https://auth.notabene.id \
      -e AUDIENCE=https://api.notabene.dev \
      -e BASE_URL=https://api.notabene.dev \
      -e AUDIENCE_PII=https://pii.notabene.dev \
      -e BASEURL_PII=https://pii.notabene.dev \
      -e KEYS='[{"vaspDID":"did:ethr:0x1111111","privateKeyHex":"987654321___123456789"}]' \
      notabene-agent
      
   // By default the Notabene Agent listens on port 3000. The -p option maps a host port to the container port.
   // The KEYS argument is optional, but required for Hybrid and E2E encryption flows.

Use the container proxy server:

   POST http://localhost:3000/tx/create

API reference

Almost all endpoints are identical to our API documetation (https://doc.notabene.id/). Except you do not need to provide an authorization header, the agent takes care of that using the Auth0 ClientId and ClientSecret credentials.

E2E Encryption

Requirement: For this flow your VASP needs to have an encryption keypair. To generate a new keypair call the following endpoint: GET http://localhost:3000/didkey/new. The output will contain several fields that need to be processed:

  1. Update your VASP in the Notabene network to set its pii_didkey field to this did:key:... value.
  2. Use the privateKeyHex value to initialize the Notabene Agent with the KEYS argument, associating your vaspDID with this private key.
  • POST localhost:3000/tx/create -- creates a transaction and encrypts the PII data if the originatorVASPdid appears in the KEYS. If the beneficiaryVASPdid has no pii_didkey it will only encrypt for the originator.
  • GET localhost:3000/tx/info?id=txid&vaspDID=did:ethr:0x123 -- gets the transaction & decrypts the PII data if the vaspDID appears in the KEYS. When managing multiple VASPs you may not know the originatorVASPdid given a transaction ID, in that case you can call this endpoint twice.
  • POST localhost:3000/tx/update -- updates a transaction and decrypt the PII data if the originatorVASPdid appears in the KEYS. If the beneficiaryVASPdid has no pii_didkey it will only encrypt for the originator.

Hybrid Encryption

Requirement: For this flow your VASP needs to have an encryption keypair. (see E2E Encryption)

  • POST localhost:3000/tx/create?hybrid=1 -- creates a transaction and encrypts the PII data if the originatorVASPdid appears in the KEYS. If the beneficiaryVASPdid has no pii_didkey it will only encrypt for the originator.
  • GET localhost:3000/tx/info?id=txid -- because of hybrid encryption only the transaction ID is required.
  • POST localhost:3000/tx/update?hybrid=1 -- updates a transaction and decrypt the PII data if the originatorVASPdid appears in the KEYS. If the beneficiaryVASPdid has no pii_didkey it will only encrypt for the originator.

Updated 12 months ago