Quick Start Guide

Store Your First Document in 5 Minutes

The TrueVault API is incredibly easy to get started with. This guide will walk you through the steps you need to take to store and retrieve your first Document in TrueVault. We hope this guide will give you a sense of just how simple it is to integrate TrueVault with your project.

1. Create an Account

First, you'll need to create a TrueVault account. You do not need to give us a payment method and you can use this account in development mode for as long as you wish.

Tip: Every account starts out as a development account which means you should not store any Protected Health Information in TrueVault until you have activated your account and you have executed a Business Associate Agreement. You can email us (help@truevault.com) for a copy of the Business Associate Agreement before you sign up.

Create Account

2. Create a Vault

Next, we'll create a Vault to store your first Document. Once you are registered, you'll be taken to the Management Console Dashboard. From there, click the Explorer menu item on the top menu bar and then click the "Create New Vault" button in the bottom left. Name the Vault "Quick Start" then click "save." Now a Vault is created and it's ready to store any JSON or BLOB objects.

Tip: There is no limit on the number of Vaults you can create, and the number of vaults you have will depend on your specific use case and data model.

Create Vault

3. Create a User

Next, we need to create a User so you have an API key for the API call. Click on the Users menu item on the top menu bar then click the "Add +" button. Name the new user "quickstart" then click "Save."

Create User

For the sake of this quickstart, give this user Full Admin access to your account. To do this, copy the user id from the url and then navigate to the groups page by clicking on the Groups menu item on in the top menu bar. Select the group named "FULL_ADMIN". Then click the "Add +" button in the users list on the right hand side. Enter your quickstart user id and hit save.

Make User Admin

Now this user has full access to your account. Generate an API Key by returning to the user page, selecting your quickstart user on the left, and clicking "Reassign" on the top next to API Key.

Regenerate API Key Confirm

You'll be asked to confirm, then shown your API Key.

Regenerate API Key Review

Tip: Because this API key authorizes access to your Vaults, please do not share your API keys and do rotate API keys frequently. In practice, avoid having Full Admin users, and instead give them the minimal set of permissions they need by creating a group with specific policies statements.

Tip: As with Vaults, you can create as many User accounts as you need. We recommend you create an User account for each system user (migrations, scheduled jobs, etc) and for each end user. This allows you to be granular with appropriate access control.

4. Create a Document

Now that we have a Vault to store our test Document and an User account with an API key, we are ready to POST our test Document. To construct the cURL POST command, you will need both the Vault ID and the API key you created earlier. You can find them in the Management Console.

For this example, we'll use this Document:

{"hello":"world"}

The Base64 encoded Document is eyJoZWxsbyI6IndvcmxkIn0=.

Using your Vault ID, the API Key, and the Base64 encoded JSON document, run the following cURL command:

curl -X POST https://api.truevault.com/v1/vaults/[your_vault_id]/documents \
-u [your_api_key]: \
-d "document=eyJoZWxsbyI6IndvcmxkIn0="

You should get a success response from the TrueVault API:

{
  "document": {
    "id": "65de7841-6770-48aa-bb4a-60c93158349b",
    "vault_id": "9e0b0274-bd57-419f-baa7-9f0ffb8e87fb"
  },
  "document_id": "65de7841-6770-48aa-bb4a-60c93158349b",
  "result": "success",
  "transaction_id": "49ca0e7b-a205-4f10-9714-125668730948"
}

Tip: The document_id in the response is your reference to the document. You will need it to delete, update or get the document from TrueVault.

Tip: You can also manually edit documents through the console, by selecting the vault in the Explorer tab. This allows you to read, update, and even search your documents.

There! You have successfully stored your first document in TrueVault. Let's retrieve it.

5. Read a Document

To retrieve the Document you just stored in TrueVault, run this command with your Vault ID, your API Key and the document_id from the POST response.

curl https://api.truevault.com/v1/vaults/[your_vault_id]/documents/[document_id] \
-u [your_api_key]: 

The response of the GET action will be the document you posted earlier (still base64 encoded).

Alright, there you go. This is how you store and retrieve your first document from TrueVault.

Latest Posts

Mailing List

Subscribe to our mailing list