API Reference

The Evervault API allows developers to interact programmatically with their Evervault apps using HTTP requests. The Evervault API is built around REST.

The API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

Authentication

The Evervault API uses API keys to authenticate requests. You can view and manage your API keys in the App Settings section of the Evervault dashboard.

Requests are authenticated via HTTP Basic Auth. Provide your app ID as the basic auth username and your API key as the password.

If you are handling the Authorization header yourself, you will need to base64 encode the app ID and API key before sending the request:

  1. If your App ID is app_1234, and your API key is ev:key:1:abcdefd, then combined they'd be app_1234:ev:key:1:abcdefd.
  2. Base64 encode the combined string to get YXBwXzEyMzQ6...
  3. Use the encoded string as the value for the Authorization header. Authorization: Basic YXBwXzUyMzQ6...
Example

Errors

Evervault uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate the request has failed. Codes in the 5xx range indicate an error with Evervaults’ servers.

Errors returned from the API follow the Problem JSON spec and will be returned as JSON with a Content-Type of application/problem+json.

Response Body
codestring
A distinct error code, presented in slug format, that identifies a specific error.
titlestring
A short, human-readable summary of the error.
statusinteger
The HTTP status code for the error.
detailstring
A human-readable explanation of the error.
Example

Encrypt

The encrypt endpoint can be used to encrypt the values of a JSON object, or file. 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.

Request Body

A JSON value or file to be encrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).

Response

An encrypted JSON object or file. For JSON requests, The payload structure will be the same as the one in the request payload, with all of the values encrypted.

post/encrypt
200
Response

Decrypt

The decrypt endpoint can be used to decrypt the values of a JSON object, or file. 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.

Authorization
API Key Permissions
This endpoint must be called using an API key with the Decrypt permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Client-Side Token
This endpoint can also be authenticated using a Client-Side Token with the action api:decrypt
Request Body

A JSON value or file to be decrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).

Response

A decrypted JSON object or file. For JSON requests, The payload structure will be the same as the one in the request payload, with any encrypted values decrypted.

post/decrypt
200
Response

Inspect

Retrieve metadata for an encrypted value such as the time of encryption, the type of data, the data role and category-specific metadata (e.g. card metadata) without accessing the plaintext value.

Authorization
API Key Permissions
This endpoint must be called using an API key with the Inspect permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Request Body

A JSON-formatted string representing the encrypted data to be inspected. Ensure that the string is wrapped in double quotes.

Response
typeinteger | float | boolean | string

The type of the encrypted value.

categorycard-number

The category or specific nature of the encrypted value.

encryptedAtstring

The date and time when the value was encrypted. This is a Unix timestamp in milliseconds. This field is currently only populated for values encrypted with a Data Role.

rolestring

The data role of the encrypted value.

fingerprintstring

A unique identifier for the encrypted value.

metadata

Further metadata about the encrypted value. Returns different information based on the category of the data.

post/inspect
200
Response

Run a Function

The Function run endpoint lets you invoke an Evervault Function. The body of the request should contain a payload, the value of which will be decrypted and passed as an argument to the Function.

Parameters
function_name
The name of the Function to be executed.
Request Body
payloadRequiredobject

The data payload that the Function will use during its execution. Any encrypted values will be decrypted before being passed to the function.

Response
idstring

A unique identifier representing this specific Function execution instance.

statussuccess | failure

The outcome of the Function execution. A 'success' denotes successful execution, whereas a 'failure' indicates that the Function encountered an error.

resultobject

This field represents the output returned by the Function. This is provided only when the Function execution status is 'success'.

errorobject

This field details any error that occurred during Function execution. This is present only if the status is 'failure'.

createdAtinteger

The exact time, in epoch milliseconds, when this Function execution was triggered.

post/functions/:function_name/runs
200
Response

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.

After creating a Client-Side Token, you can use it to authenticate requests to the Evervault API by providing it in the Authorization header. The token is a JWT, and should be included in the header in the format:

Authorization: Token <client-side-token>

Example

Create a client token

Client-Side Tokens are restricted to specific payloads. By default, a Client-Side Token will expire after 5 minutes. The maximum expiration time of a token is 10 minutes. When using the REST API, the expiry field must be in epoch milliseconds.

Request Body
actionRequiredapi:decrypt

The action that the token should permit

payloadobject

The payload that the token must be used with

expiryinteger

The expiry of the token in milliseconds format. Must be less than 10 minutes from now.

Response
idstring

The id of the token

tokenstring

The token

expiryinteger

The expiry of the token in unix millis format

createdAtinteger

The creation time of the token in unix millis format

post/client-side-tokens
201
Response