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:
Copy the key and store it somewhere safe — it’s the equivalent of a password giving full access to your Compliance Vault data:
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:
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!