Using the Compliance Vault REST API

ProvenDB Compliance Vault provides a tamper-resistant digital store for your critical documents. We guarantee the origin, ownership, versioning, and security of your documents to satisfy the most rigorous audit. Under the hoods, documents in the compliance vault are stored in ProvenDB — a database service that uses blockchain technology to create the world’s first truly trustworthy database.

Documents in ProvenDB Compliance Vault can be uploaded and accessed via an easy to use Web interface or can be emailed into the system. However, you can also use the Compliance Vault REST API to integrate Compliance Vault document services into an existing application or automation workflow.

Let’s see how it works.

First, we need to get an API key from ProvenDB. From the “Manage API Keys” section of ProvenDB.com we can create a new API key:

Figure 1: Defining an API key

Copy the key and store it somewhere safe — it’s the equivalent of a password giving full access to your Compliance Vault data:

Figure 2: The resulting API key

One of the great things about REST is that it can be used from any language and from a wide variety of frameworks. For these examples, I’m going to use Axios within a NodeJS application.

I need to import the Axios package, and define my API Key:

Uploading documents

The uploadFile route allows you to add a file to the compliance vault. Below is a simple Axios-based function that adds a file to the vault:

Note that you can encode the file however you like, but the base64 encoding above is the standard for compliance vault and allows us to provide previews and thumbnails in the UI.

Files uploaded to the Compliance Vault can be viewed in the api folder of the compliance vault:

Figure 3: Document and proof in the Compliance Vault

Working with proofs and documents

The API provides routes that allow you to retrieve your document and to navigate document metadata.

This code retrieves the latest version of a document and saves it to disk:

This code will retrieve and save the Blockchain Proof Certificate shown in Figure 3:

Additional API calls

The REST API includes routes for other Compliance vault operations:

• The updateFile PUT call creates a new version of an existing file. The old version is maintained and its proof remains valid.
• The getFileHstory GET call retrieves the version history for a file.
• The filePreview GET route retrieves a preview “thumbnail” of a file.
• The getAuditHistory GET route retrieves an audit history of REST calls against the file.
• The forgetFile DELETE route “Forgets” a file. The file’s hash and history is retained, but all document content is redacted.
• The getProof GET call gets a provenDB proof for the file in the chainpoint open format.

Getting started

You can sign up for a free Compliance Vault account here. The full documentation for Compliance Vault is available in our documentation set.

For the REST API, the full reference is here: https://compliancevault.readme.io/reference, and there is a postman collection containing all the defined routes here: https://www.postman.com/collections/91a7506f87f8f98e35b8

We’d love to know what you think about the Compliance Vault API and always welcome ideas for new functionality!