Overview¶

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.

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.

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"
}