TrueVault API Overview

TrueVault Introduction


TrueVault is a secure data vault. It is designed from the ground up to provide regulatory compliant storage for Protected Health Information (PHI) and Personally Identifiable Information (PII).

TrueVault provides a simple REST API that can be used to store and retrieve any amount of data, at any time, from anywhere on the web. It gives developers the freedom to create applications that require regulatory compliance without worrying about regulatory compliance.


  • Ensures your application meets the HIPAA technical and physical safeguards.
  • Provides user identity and access control for your application.
  • Stores your application’s PHI and PII using industry best-practices.



TrueVault forces HTTPS for all services. We regularly audit the details of our implementation: the certificates we serve, the certificate authorities we use, and the ciphers we support. We use HSTS to ensure browsers interact with TrueVault only over HTTPS.


All records are encrypted with AES using 256bit encryption keys before they are stored on disk. Decryption keys are stored in a separate key management cluster to restrict access. None of TrueVault’s internal servers and daemons are able to obtain plaintext PHI or PII; instead, they can just request that data be sent to a service provider on a static whitelist. TrueVault’s infrastructure for storing, decrypting, and transmitting protected information runs in separate hosting infrastructure and doesn't share any credentials with TrueVault’s primary services (API, website, etc.).

Additionally, every protected record is encrypted with a unique initialization vector and a unique encryption key. Record integrity is enforced with a hash-based authentication code (HMAC) calculated using its own unique 256bit HMAC key.

TrueVault verifies each record’s integrity on a scheduled basis and on each record request. Encryption keys, initialization vectors and HMAC keys are re-keyed on a regular basis.


Every user action and API call is logged by TrueVault. In the event of an audit, TrueVault will provide detailed logs showing which users performed which actions. Audit logs include specific actions (e.g. Create, Read, Delete) and specific resource identifiers (e.g. Blob Id, Document Id, Vault Id)

TrueVault and Entities


Account is the highest level of abstraction in TrueVault. Typically an organization will have only one account. Many lower level data are rolled up to the account level for easier management. For example, billing is done at the account level and users and user groups are managed at the account level. One account has one account owner and it is the person who created the account. An account can have multiple vaults, schemas, users and user groups.


A vault is a container of documents and BLOBs. Multiple vaults can be created for an account and by default the user who creates the vault is also the owner of the vault. An organization may want to create vaults that map to each application environment (production, staging, QA, demo, etc.), each developer and each development branch. Documents and BLOBs can not be shared between multiple vaults.


A document is a text record and has a collection of fields. TrueVault differentiates text-based and binary-based records for multiple reasons: available operations, storage location and billing. A TrueVault document is a schema-less JSON document. You can optionally apply a schema to your documents, indicating which field in the document should be indexed by our HIPAA-compliant search engine. All operations on a document are logged at the record level. For example, if a user requests a list of documents, TrueVault will record individual view requests for each document in the list. When reading or writing a document, TrueVault verifies the user has permission to do so at the document level.


A BLOB is a binary record. TrueVault treats a BLOB as a black box entity and will not try to derive meaning from it. Applications can store binary files such as PDFs, images, videos in TrueVault as a BLOB.


A user can interact with TrueVault. Conceptually there are two types of users: a person and an application. When an user is created, only a username is required. For a person, typically the person’s email address or the person’s name is used. For an application, typically the name of the application is used (e.g., production_web). An API Key can be added to the user allowing the user to be identified by our API. Usually an API key is assigned to an application or a person who is a developer. A password can also be assigned to a user. Usually a password is assigned to a person thus allowing that person to be authenticated for your application.


Remember that all Protected Health Information should only traverse through HIPAA compliant environments. If you plan on using any of the server-side libraries, please ensure any hosting environment you use is HIPAA compliant. TrueVault does not ensure HIPAA compliance for data stored outside of TrueVault.

Latest Posts

Mailing List

Subscribe to our mailing list