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).

post/encrypt
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.

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).

post/decrypt
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.

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.

post/inspect
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.

200
Response

List all Relays

Request Body
No request body
get/relays
Response
dataarray

An array of Relays belonging to the App.

200
Response

Create a Relay

Request Body
destinationDomainRequiredstring

The domain in front of which you would like to configure a Relay

routesRequiredarray

A collection of route configurations for the Relay.

encryptEmptyStringsboolean

Whether or not empty strings should be encrypted. Defaults to true.

authentication"api-key" | null

The type of authentication required for the Relay.

post/relays
Response
idstring

The unique identifier for the Relay.

destinationDomainstring

The domain in front of which the Relay should be configured.

evervaultDomainstring

The Evervault managed domain to which requests to be relayed to the destination domain should be sent.

routesarray

A colletion of route configurations for the Relay.

authenticationapi-key

The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.

encryptEmptyStringsboolean

Whether or not empty strings should be encrypted.

appstring

The unique identifier for the app to which the Relay belongs.

createdAtinteger

The exact time, in epoch milliseconds, when this Relay was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Relay was updated.

201
Response

Retrieve a Relay

Parameters
relay_id
The id of the Relay to be fetched.
Request Body
No request body
get/relays/:relay_id
Response
idstring

The unique identifier for the Relay.

destinationDomainstring

The domain in front of which the Relay should be configured.

evervaultDomainstring

The Evervault managed domain to which requests to be relayed to the destination domain should be sent.

routesarray

A colletion of route configurations for the Relay.

authenticationapi-key

The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.

encryptEmptyStringsboolean

Whether or not empty strings should be encrypted.

appstring

The unique identifier for the app to which the Relay belongs.

createdAtinteger

The exact time, in epoch milliseconds, when this Relay was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Relay was updated.

200
Response

Updates a Relay

Parameters
relay_id
The id of the Relay to be updated.
Request Body
routesarray

A collection of route configurations for the Relay. Any existing route configurations will be replaced with the new configurations.

encryptEmptyStringsboolean

Whether or not empty strings should be encrypted.

authentication"api-key" | null

The type of authentication required for the Relay.

patch/relays/:relay_id
Response
idstring

The unique identifier for the Relay.

destinationDomainstring

The domain in front of which the Relay should be configured.

evervaultDomainstring

The Evervault managed domain to which requests to be relayed to the destination domain should be sent.

routesarray

A colletion of route configurations for the Relay.

authenticationapi-key

The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.

encryptEmptyStringsboolean

Whether or not empty strings should be encrypted.

appstring

The unique identifier for the app to which the Relay belongs.

createdAtinteger

The exact time, in epoch milliseconds, when this Relay was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Relay was updated.

200
Response

Delete a Relay

Parameters
relay_id
The id of the Relay to be deleted.
Request Body
No request body
delete/relays/:relay_id

List all Custom Domains

Parameters
relay_id
The id of the Relay whose custom domains should be fetched.
Request Body
No request body
get/relays/:relay_id/custom-domains
Response
dataarray
200
Response

Create a Custom Domain

Creates a custom domain for the Relay

Parameters
relay_id
The id of the Relay to which the custom domain should be added.
Request Body
customDomainRequiredstring

The customer managed domain to which requests to be relayed to your domain should be sent.

post/relays/:relay_id/custom-domains
Response
idstring

The unique identifier for the custom domain.

customDomainstring

The customer managed domain to which requests to be relayed to your domain should be sent.

relaystring

The ID of the Relay with which this custom domain is associated.

statuspending | active | inactive

The status of the domains DNS verification.

createdAtinteger

The exact time, in epoch milliseconds, when this custom domain was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this custom domain was last updated.

201
Response

Retrieve a Custom Domain

Parameters
relay_id
The id of the Relay to which the custom domain belongs.
custom_domain_id
The id of the custom domain to be fetched.
Request Body
No request body
get/relays/:relay_id/custom-domains/:custom_domain_id
Response
idstring

The unique identifier for the custom domain.

customDomainstring

The customer managed domain to which requests to be relayed to your domain should be sent.

relaystring

The ID of the Relay with which this custom domain is associated.

statuspending | active | inactive

The status of the domains DNS verification.

createdAtinteger

The exact time, in epoch milliseconds, when this custom domain was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this custom domain was last updated.

200
Response

Delete a Custom Domain

Parameters
relay_id
The id of the Relay to which the custom domain belongs.
custom_domain_id
The id of the custom domain to be deleted.
Request Body
No request body
delete/relays/:relay_id/custom-domains/:custom_domain_id

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.

asyncboolean

If you want your Function to run asynchronously and notify a callback URL, this can be set to true and the API will queue your Function run and return a 202 response code.

post/functions/:function_name/runs
Response
idstring

A unique identifier representing this specific Function execution instance.

statussuccess | failure | scheduled

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.

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.

post/client-side-tokens
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

201
Response

Create a Merchant

Creates a Merchant. Creating a merchant is a prerequisite for the issuance of Network Tokens, as these tokens are uniquely associated with and scoped to a specific Merchant.

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

The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname.

websiteRequiredstring

The official website URL of the Merchant.

categoryCodeRequiredstring

The 4-digit Merchant Category Code (MCC).

businessRequiredobject

The business details of the Merchant.

networkTokensobject

The Merchant's Network Tokens configuration. This field should only be populated if the Merchant has already been enrolled in one of the Card Network programs and can use an existing Token Requestor ID (TRID).

post/payments/merchants
Response
idstring

A unique identifier assigned to each Merchant.

namestring

The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname.

websitestring

The official website URL of the Merchant.

businessobject

The business details of the Merchant.

categoryCodestring

The 4-digit Merchant Category Code (MCC).

networkTokensobject

The Merchant's Network Token configuration.

liveModeboolean

A boolean value indicating whether the Merchant is in live mode (true) or in test mode (false).

createdAtinteger

The exact time, in epoch milliseconds, when this Merchant was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Merchant was last updated.

201
Response

Retrieve a Merchant

Retrieves a Merchant by its unique identifier.

Authorization
API Key Permissions
This endpoint must be called using an API key with the Retrieve Merchant permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
merchant_id
The unique identifier of the merchant.
Request Body
No request body
get/payments/merchants/:merchant_id
Response
idstring

A unique identifier assigned to each Merchant.

namestring

The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname.

websitestring

The official website URL of the Merchant.

businessobject

The business details of the Merchant.

categoryCodestring

The 4-digit Merchant Category Code (MCC).

networkTokensobject

The Merchant's Network Token configuration.

liveModeboolean

A boolean value indicating whether the Merchant is in live mode (true) or in test mode (false).

createdAtinteger

The exact time, in epoch milliseconds, when this Merchant was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Merchant was last updated.

200
Response

Create a Network Token

Create a Network Token for a given card.

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

The unique identifier of the Merchant previously created using the Evervault API. It denotes the Merchant to which the Network Token should be associated with.

post/payments/network-tokens
Response
idstring

A unique identifier representing a specific Network Token.

numberstring

The unique number of the Network Token.

expiryobject

The expiry details of the Network Token.

cardobject

The details of the underlying tokenized card.

tokenRequestorIdentifierstring

The identifier of the Token Requestor (TRID) that requested the Network Token.

tokenServiceProvidermdes | vts | aets

The Token Service Provider (TSP) that issued the Network Token.

paymentAccountReferencestring

The unique identifier of the Payment Account associated with this Network Token.

statusactive | inactive

The status of the Network Token. Active means the Network Token is valid and can be used for payments.

merchantstring

The unique identifier of the Merchant associated with this Network Token.

liveModeboolean

A boolean value indicating whether the Network Token is in live mode (true) or in test mode (false).

createdAtinteger

The exact time, in epoch milliseconds, when this Network Token was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Network Token was last updated.

201
Response

Retrieve a Network Token

Retrieves a Network Token by its unique identifier.

Authorization
API Key Permissions
This endpoint must be called using an API key with the Retrieve Network Token permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
network_token_id
The unique identifier of the Network Token.
Request Body
No request body
get/payments/network-tokens/:network_token_id
Response
idstring

A unique identifier representing a specific Network Token.

numberstring

The unique number of the Network Token.

expiryobject

The expiry details of the Network Token.

cardobject

The details of the underlying tokenized card.

tokenRequestorIdentifierstring

The identifier of the Token Requestor (TRID) that requested the Network Token.

tokenServiceProvidermdes | vts | aets

The Token Service Provider (TSP) that issued the Network Token.

paymentAccountReferencestring

The unique identifier of the Payment Account associated with this Network Token.

statusactive | inactive

The status of the Network Token. Active means the Network Token is valid and can be used for payments.

merchantstring

The unique identifier of the Merchant associated with this Network Token.

liveModeboolean

A boolean value indicating whether the Network Token is in live mode (true) or in test mode (false).

createdAtinteger

The exact time, in epoch milliseconds, when this Network Token was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Network Token was last updated.

200
Response

Delete a Network Token

Deletes a Network Token by its unique identifier.

Authorization
API Key Permissions
This endpoint must be called using an API key with the Delete Network Token permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
network_token_id
The unique identifier of the Network Token.
Request Body
No request body
delete/payments/network-tokens/:network_token_id
204
Response

Create a Cryptogram

Creates a Network Token Cryptogram.

Authorization
API Key Permissions
This endpoint must be called using an API key with the Create Network Token Cryptogram permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
network_token_id
The unique identifier of the Network Token.
Request Body
No request body
post/payments/network-tokens/:network_token_id/cryptograms
Response
idstring

A unique identifier representing a specific Network Token Cryptogram.

cryptogramstring

The value of the Network Token Cryptogram. This is the value that is used embedded in the Authorization request.

liveModeboolean

A boolean value indicating whether the Network Token Cryptogram is in live mode (true) or in test mode (false).

createdAtinteger

The exact time, in epoch milliseconds, when this Network Token Cryptogram was created.

201
Response

List all Webhook Endpoints

Lists all Webhook Endpoints

Authorization
API Key Permissions
This endpoint must be called using an API key with the List Webhook Endpoints permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
limit
The maximum number of Webhook Endpoints to return (Default is 10).
startingAfter
The identifier of the last Webhook Endpoint in the previous page of results.
Request Body
No request body
get/webhook-endpoints
Response
dataarray
hasMoreboolean

Indicates whether there are more Webhook Endpoints to retrieve.

200
Response

Create a Webhook Endpoint

Create a Webhook Endpoint

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

The URL of the Webhook Endpoint.

eventsRequiredarray

A list of Events that the Webhook Endpoint is subscribed to. The following events are supported:

  • payments.merchant.updated: A Merchant was updated
  • payments.network-token.updated: A Network Token was updated
  • function.run.completed: An asynchronous Function Run was completed
post/webhook-endpoints
Response
idstring

A unique identifier representing a specific Webhook Endpoint.

urlstring

The URL of the Webhook Endpoint.

eventsarray

A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.

createdAtinteger

The exact time, in epoch milliseconds, when this Webhook Endpoint was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Webhook Endpoint was last updated.

201
Response

Retrieve a Webhook Endpoint

Retrieves a Webhook Endpoint

Authorization
API Key Permissions
This endpoint must be called using an API key with the Get Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
webhook_endpoint_id
The identifier of the Webhook Endpoint to retrieve.
Request Body
No request body
get/webhook-endpoints/:webhook_endpoint_id
Response
idstring

A unique identifier representing a specific Webhook Endpoint.

urlstring

The URL of the Webhook Endpoint.

eventsarray

A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.

createdAtinteger

The exact time, in epoch milliseconds, when this Webhook Endpoint was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Webhook Endpoint was last updated.

200
Response

Update a Webhook Endpoint

Updates a Webhook Endpoint

Authorization
API Key Permissions
This endpoint must be called using an API key with the Update Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
webhook_endpoint_id
The identifier of the Webhook Endpoint to update.
Request Body
eventsRequiredarray

A list of Events that the Webhook Endpoint is subscribed to. The following events are supported:

  • *: All Events
  • payments.merchant.updated: A Merchant was updated
  • payments.network-token.updated: A Network Token was updated
  • function.run.completed: An asynchronous Function Run was completed
patch/webhook-endpoints/:webhook_endpoint_id
Response
idstring

A unique identifier representing a specific Webhook Endpoint.

urlstring

The URL of the Webhook Endpoint.

eventsarray

A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.

createdAtinteger

The exact time, in epoch milliseconds, when this Webhook Endpoint was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this Webhook Endpoint was last updated.

200
Response

Delete a Webhook Endpoint

Delete a Webhook Endpoint

Authorization
API Key Permissions
This endpoint must be called using an API key with the Delete Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.
Parameters
webhook_endpoint_id
The identifier of the Webhook Endpoint to delete.
Request Body
No request body
delete/webhook-endpoints/:webhook_endpoint_id
204
Response