Overview

The TrueVault API is composed of “resources” that you can manipulate through a REST API. All resources can be interacted with a variety of HTTP Methods, and most support methods to list, create, read, update, and delete either specific or all resources. All resources have an accompanying resource “id” that is generated by the TrueVault servers and is usually how you reference resources for manipulation via the API.

A TrueVault resource URI is composed of 3 components, the host url, the api version, and the resource identifier.

The host url should be https://api.truevault.com, the version v1, and then the resource identifier provided by the documentation.

For example to retrieve a document from though the v1 JSON Documents API you would issue a request to the following URI: https://api.truevault.com/v1/vaults/<vault_id>/documents/<document_id>


Authentication

You must authenticate to use the TrueVault REST API. This can be done either through an API Key or an API Access Token. By default, a user will need to be issued an API_KEY via Management Console or via the Users API. An ACCESS_TOKEN can only be issued via the Users API.

Both authentication schemes require that you provide the key or token using the HTTP Basic Authorization Header; you must provide the API_KEY or ACCESS_TOKEN as the username and an empty string as the password.

Building the Auth Header

For example, to make a request with an API_KEY of 00000000-0000-0000-0000-000000000000, first append a colon and Base64 encode the string. The resulting header is the following:

Authorization: Basic MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwOg==

If instead you have an ACCESS_TOKEN like .eJwli0EKwjAQAP-Sqy5sN5vG7QMUPXsvm2YDpVTFtgcR_27Q2zDMvN06zrasOj9c5wibCEiA8YrY, you would still append the colon and Base64 the resulting string. This would give a header that looks like this:

Authorization: Basic LmVKd2xpMEVLd2pBUUFQLVNxeTVzTjV2RzdRTVVQWHN2bTJZRHBWVEZ0Z2NSXzI3UTJ6RE12TjA2enJhc09qOWM1d2liQ0VpQThZclk6

When you’re getting started with the API, you may want to get the basics down with curl. These commands show how you can make an authenticated request from a bash-like shell:

# 1. Put either your API Key or your User Access Token in this variable.
export API_KEY_OR_TOKEN='put yours here'
# 2. Append the ':' character
export RAW_HEADER_PAYLOAD=${API_KEY_OR_TOKEN}:
# 3. base64 encode the concatenated string
export ENCODED_HEADER_PAYLOAD=`echo -n ${RAW_HEADER_PAYLOAD} | base64`
# 4. Make a request, specifying that payload in the
#    Authorization header with the 'Basic' prefix
curl -H "Authorization: Basic ${ENCODED_HEADER_PAYLOAD}" https://api.truevault.com/v1/auth/me

API Keys

An API_KEY does not expire unless explicitly expired via the Management Console or via the Users API. We recommend that you ensure these are stored safely as they do not expire and could have full access to the TrueVault REST API. We recommend that you use these for Administrators, Owners, and Developers and consider using an ACCESS_TOKEN for regular users.

Warning

For your security, a user’s API_KEY will only be shown upon user creation via the API or TrueVault Management Console. If lost, the API_KEY can be retrieved or re-generated via the TrueVault Management Console or by using the Users API’s POST /api_key endpoint. You must have U group permissions on the target user.

User Access Tokens

By default, a User Access Token expires 24 hours from when it is issued by the TrueVault API. The expiration time can be overridden by specifying the not_valid_after parameter in the /auth/login endpoint. The /auth/login endpoint will generate a new User Access Token in exchange for a user’s username and password. This is the common way to generate User Access Tokens for end-users. You can also generate a User Access Token using the `/users/<user_id>/access_token`` endpoint, but this request must be authenticated with an API Key or a User Access Token for a user that has the U group permission on the target user.


API Requests

All TrueVault API request must have an Authorization header, please see individual API endpoints for valid Authorization schemes.


API Responses

TrueVault uses HTTP status codes whenever possible. In general, 2xx class indicate success, 4xx indicate an client error, and 5xx indicate a server error. When available, the TrueVault REST API will respond with additional information that may help diagnose the cause of the error.

Occasionally, an unexpected input may result in a 5xx series error, if you feel that the TrueVault API behaves contrary to what is found in our documentation, please contact us. You can use the support widget inside the TrueVault Console

Warning

Certain endpoints in the Documents/BLOBs API will respond directly with an encoded object.

Warning

Fields that are expected to be returned but do not contain a value will return null instead of being omitted. For example, when Listing all Documents, some Documents may not have an owner. These entries will have a null value in the owner_id field.

Sample 2xx Response

{
    "user": {
        "account_id": "00000000-0000-0000-0000-000000000000",
        "api_key": "00000000-0000-0000-0000-000000000000",
        "status": 1,
        "id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Sample 4xx Response

{
    "error": {
        "code": 400,
        "message": "Invalid request. Missing required fields",
        "type": "invalid_request_error"
    },
    "result": "error",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Usage Tracking (Billing)

TrueVault accounts are billed based on how many Operations each account performs every month and how much BLOB data is stored.

All API calls consume at least one operation. Multiget, list, and search endpoints consume additional operations if “full documents” (decrypted content) are returned. For list endpoints that only return metadata (e.g. list all document ids in a vault), only a single operation is consumed.

Endpoints that use more than a single operation describe their usage behavior in the API Documentation.