NAV Navbar
shell javascript

Introduction

Welcome to the evervault API! You can use our API to manage and deploy evervault cages, which allow you to deploy your applications on secure, privacy-preserving infrastructure in under 30 seconds.

We have a JavaScript SDK as well as a CLI, with support for other languages coming soon. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

We're currently onboarding an average of 5 companies per week to use our platform. To join the waiting list, register at the evervault website.

Authentication

To authorize, use this code:

# With curl, make sure to replace "sesame" with a HTTP Basic Auth string
# i.e. a Base64 encoded string of email:password
curl https://api.evervault.com/auth
  -X POST
  -H "Authorization: Basic opensesame"

# Alternatively, you can install the evervault CLI by running
npm install -g evervault-cli

# Then you can authenticate by running
evervault login

const evervault = require('evervault')('opensesame')

Make sure to replace opensesame with your API key.

evervault uses Bearer Tokens to authenticate requests to the API. You can retrieve a JWT-encoded API Bearer Token by sending a POST request to the /auth endpoint with a Basic Auth Base64-encoded credential string.

evervault API credentials can be changed in the developer portal.

evervault expects the API token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer opensesame

Cages

List all Cages

# Using cURL
curl https://api.evervault.com/cages
  -H "Authorization: Bearer opensesame"

# Using the evervault CLI
evervault cage:list

const evervault = require('evervault')('opensesame');

evervault.cages.list((err, cages) => {
  // err should == false if everything went well
  // cages is a JavaScript array containing an object for each cage
});

The above command returns JSON structured like this:

{
  "count": 19,
  "rows": [
    {
      "id": "5d8dfd9953992100d1f4f59a",
      "user": {
        "id": "5d77c83a07897400bdcc2342",
        "picture": "https://gravatar.com/avatar/0c81974ec8f93394b84e23c0a2880afa?d=identicon"
      },
      "metadata": {
        "framework": "nodejs",
        "libraries": [],
        "original_source": "…"
      },
      "status": "deployed",
      "url": "https://ev.run/summer-glade-8854",
      "source": "…",
      "name": "summer-glade-8854",
      "keys": {
        "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFz3Q1tkKo6w/8mliv47AUdPqasOPddYor9nrQggqt95g7EoSpZ9E/YT/o1gKOF4NB9omo+NAkgmANFEfdX4/xA=="
      },
      "createdAt": "2019-09-27T12:16:25.732Z",
      "updatedAt": "2019-09-27T12:16:26.931Z"
    },
    { … }
  ]
}

This endpoint retrieves a list of your deployed cages.

HTTP Request

GET https://api.evervault.com/cages

Deploy a Cage

curl "https://api.evervault.com/cages"
  -H "Authorization: opensesame"
  -H "Content-Type: application/json"
  -X POST
  -d '{
    source: "...",
    metadata: { ... }
  }'

const evervault = require('evervault')('opensesame');

evervault.cage.deploy(function () {
  // Insert your code here
}, function (error, data) {
  // error === any errors thrown
  // should === false

  // data === a JSON object with the new cage details
});

The above command returns JSON structured like this:

{
  "id": "5d921c3453992100d1f4f59d",
  "user": {
    "id": "5d77c83a07897400bdcc2342",
    "name": "shane",
    "email": "shane@evervault.com",
    "createdAt": "2019-09-10T15:58:50.321Z"
  },
  "metadata": {
    "framework": "node.js",
    "version": "v12.9.1",
    "original_source": "..."
  },
  "status": "building",
  "url": "https://ev.run/autumn-bush-7327",
  "source": "...",
  "name": "autumn-bush-7327",
  "createdAt": "2019-09-30T15:16:04.141Z",
  "updatedAt": "2019-09-30T15:16:04.141Z"
}

This endpoint deploys a piece of source code as a cage.

HTTP Request

POST https://api.evervault.com/cages

POST Parameters

Parameter Description
source Stringified JavaScript source code to deploy
metadata A JSON object with optional metadata

Get Cage Keys

# Using cURL
curl https://ev.run/keys/<cage>

# Using the evervault CLI
evervault cage:keys <cage>

const evervault = require('evervault')('opensesame')

evervault.cages.keys(keys => {
  // keys is an object containing the cage's key
})

The above command returns JSON structured like this:

{
  "summer-glade-8854": "3059301306072a8648ce3d020106082a8648ce3d03010703420004173dd0d6d90aa3ac3ff26962bf8ec051d3ea6ac38f75d628afd9eb42082ab7de60ec4a12a59f44fd84ffa3580a385e0d07da26a3e34092098034511f757e3fc4"
}

This endpoint retrieves the keys for a particular cage

HTTP Request

GET https://api.evervault.com/keys/<cage>

URL Parameters

Parameter Description
cage The cage name for the keys you wish to retrieve

Errors

The evervault API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The cage requested is hidden for administrators only.
404 Not Found -- The specified cage could not be found.
405 Method Not Allowed -- You tried to access a cage with an invalid method.
406 Not Acceptable -- You requested a format that isn't JSON.
410 Gone -- The cage requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many cages! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell javascript