Encryption APIs

Evervault provides APIs for encrypting and decrypting data. You can also retrieve metadata about encrypted values after they're encrypted with Evervault.

The Encrypt endpoint allows you to encrypt a JSON value or file.
The Decrypt endpoint allows you to decrypt a JSON value or file.
The Fingerprint endpoint allows you to retrieve metadata for an encrypted value.

Encrypt

Use the Encrypt API to encrypt JSON values or files. For JSON, set the Content-Type header to application/json (use application/octet-stream for files). The request body can be any valid JSON type (a dictionary, array, number, boolean, or string). When passing strings, you need to enclose them in double quotes.

1const response = await fetch("https://api.evervault.com/encrypt", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    phoneNumber: "555-2368",
9  }),
10});

The response mirrors the shape of the request, with each value replaced by its encrypted form.

1{
2  "phoneNumber": "ev:debug:Tk9D:GWgxSXezEFNw10b/:A6JZWe29uiZpP72w+nc0RXOdWdvgCulNqJv8aJpLE/gH:3V/PD54obBv0j+EJMaNNa/ny2tmZq7QM:$"
3}

Decrypt

Use the Decrypt API to decrypt JSON values or files. Values that aren't encrypted are returned unchanged.

Be careful decrypting sensitive data within your infrastructure. It could impact your compliance scope or introduce security risks. You can optionally turn on PCI mode for your app to disable the Decrypt API. If you need to share sensitive data with partners, try using Relay instead.

1const response = await fetch("https://api.evervault.com/decrypt", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    phoneNumber:
9      "ev:debug:Tk9D:GWgxSXezEFNw10b/:A6JZWe29uiZpP72w+nc0RXOdWdvgCulNqJv8aJpLE/gH:3V/PD54obBv0j+EJMaNNa/ny2tmZq7QM:$",
10  }),
11});

The response mirrors the shape of the request, with each encrypted value replaced by its decrypted form.

1{
2  "phoneNumber": "555-2368"
3}

Fingerprint

Use the Fingerprint API to retrieve metadata about an encrypted value. For example, if you pass an encrypted card, you can retrieve the card brand, the last four digits, etc.

1const response = await fetch("https://api.evervault.com/fingerprint", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    token:
9      "ev:debug:Tk9D:HBpzdbFWXbX/N2cC:AyjMY/SKO49SlkXcDPtCGs+DxnUn/F8/lAtajCYZ/xT7:KV7AUn9vJJkZDtL8PKdOc8Y11yTL2vZQasFuHqM=:$",
10  }),
11});

The API responds with an object containing details about the encrypted data, as well as the card metadata inside of the metadata field.

1{
2  "type": "string",
3  "category": "card-number",
4  "encryptedAt": 1700067122000,
5  "role": null,
6  "fingerprint": "u0ljSwrqhhUv7GykyCHB/A2bgVGXq06fnG9bOI27Sbg/tAOz3myr5zsfbasEWuMLiH6jZayu3AHGfiB7l+Bbjg",
7  "metadata": {
8    "bin": "424242",
9    "lastFour": "4242",
10    "brand": "visa",
11    "funding": "debit",
12    "segment": "consumer",
13    "country": "gb",
14    "currency": "gbp",
15    "issuer": "Gringotts Wizarding Bank and Trust Company"
16  }
17}

BIN Lookup vs. Fingerprint

Metadata	Description	Fingerprint	BIN Lookup
Fingerprint	A unique identifier for the encrypted card. This can be used to detect card reuse.
BIN	The first 6 or 8 digits of the card number.
Last 4	The last 4 digits of the card number.
Brand	The card brand, such as Visa or Mastercard.
Funding	The card funding type specifies the method by which transactions are financed (e.g. debit, credit).
Segment	The card segment indicates the primary market or usage category of the card (e.g. consumer, etc.).
Country	The country where the card was issued.
Currency	The currency of the card.
Issuer	The name of the card issuer.
Product Name	The name of the card product.
Fast Funds	Indicates whether the card supports fast funds (e.g. domestic, cross-border).
Match Precision	Indicates how many leading digits of the submitted BIN are confirmed by the matched data. A higher value means a more specific match. When multiple matches are found, the value represents the least precise BIN range the submitted BIN could belong to.
Three DS	Details on supported 3D Secure versions and ACS indicators for the card range.

See BIN Lookup for retrieving metadata for a BIN range instead of a single encrypted card.

What's next

Relay
Learn how to use Relay to encrypt or decrypt data in transit, without changing your application code.
Functions
Learn how to use Functions to process encrypted data with your own code.