Authentication

Our REST API is authenticated using HTTP Basic authorization, the header that is used is:

1
Authorization: Basic <credentials>

The credentials are created by taking your Evervault App ID and a scoped API key and combining them with a colon and finally base64 encoding them together.

For example, if your App ID is app_1234, and your scoped API key is ev:key:1:abcdefd, then combined they'd be app_1234:ev:key:1:abcdefd and finally base64("app_1234:ev:key:1:abcdefd") = YXBwXzEyMzQ6ZXY6a2V5OjE6YWJjZGVmZA==.

So the final header would be:

1
Authorization: Basic YXBwXzEyMzQ6ZXY6a2V5OjE6YWJjZGVmZA==

If you're using curl you can set the authorization header using the -u param. Curl will handle the base64 encoding.

1
curl -u "app_1234:ev:key:1:abcdefd" api.evervault.com/hello-world

Encrypt

The encrypt endpoint can be used to encrypt the values of a JSON object, or files. When encrypting the values of a JSON object the Content-Type header should be set to application/json, when encrypting files it should be set to application/octet-stream. The body of the request should the item being encrypted.

Sample Request:

curl -u "<your_app_id>:<your_api_key>" https://api.evervault.com/encrypt \
     -H "Content-Type: application/json" \
     -d '{"hello": "world"}'

1
POST https://api.evervault.com/encrypt
2
Authorization: Basic <credentials>
3
Content-Type: application/json
4
5
{
6
  "name": "Claude Shannon",
7
  "employer": {
8
    "name": "Bell Labs",
9
    "location": "Murray Hill, New Jersey"
10
  }
11
}

{
  "name":"ev:Tk9D:d5zJcOaTUeuE02...",
  "employer":{
    "location":"ev:Tk9D:pGI89owjyBx71Uge...",
    "name":"ev:Tk9D:m/y6r+yjoGkaRquc...",
  }
}

Decrypt

The decrypt endpoint can be used to decrypt the values of a JSON object, or files. When decrypting the values of a JSON object the Content-Type header should be set to application/json, when decrypting files it should be set to application/octet-stream. The body of the request should the item being decrypted.

Sample Request:

curl -u "<your_app_id>:<your_api_key>" https://api.evervault.com/decrypt \
     -H "Content-Type: application/json" \
     -d '{"hello": "ev:Tk9D:..."}'

1
POST https://api.evervault.com/encrypt
2
Authorization: Basic <credentials>
3
Content-Type: application/json
4
{
5
  "name":"ev:Tk9D:d5zJcOaTUeuE02...",
6
  "employer":{
7
    "location":"ev:Tk9D:pGI89owjyBx71Uge...",
8
    "name":"ev:Tk9D:m/y6r+yjoGkaRquc...",
9
  }
10
}

{
  "name": "Claude Shannon",
  "employer": {
    "name": "Bell Labs",
    "location": "Murray Hill, New Jersey"
  }
}

Client Side Tokens

Client Side Tokens are versatile and short-lived tokens that frontend applications can utilize to perform various actions, like running Functions or decrypting data. Client Side Tokens are restricted to specific payloads.

By default, a Client Side Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future. When using the REST API, the expiry field must be in epoch milliseconds.

Creating a Client Side Token that can decrypt data:

curl -u "<your_app_id>:<your_api_key>" https://api.evervault.com/client-side-tokens \
     -H "Content-Type: application/json" \
     -d '{"action": "api:decrypt", "payload": <payload_with_encrypted_data>, "expiry": <millisecond_epoch_time>}'

Using the token:

curl https://api.evervault.com/decrypt \
     -H "Authorization: Token <token>" \
     -H "Content-Type: application/json" \
     -d '<payload_with_encrypted_data>'