Skip to content

PEG REST API on PrivaceraCloud

PEG API Endpoint#

The PEG API endpoint is obtained using the Copy Url link in Settings > ApiKey.

In the examples here, we call this endpoint <cloud_peg_api_endpoint>.

Request Summary for PrivaceraCloud#

The PEG REST API consists of the following requests:

  • /protect - Encrypts the data.
  • /unprotect - Decrypts the data.

Prerequisites#

API Key#

For the REST API requests protect and unprotect, you need an API key. See API Key.

Scheme Policy Required for protect and unprotect API Requests#

For the REST API requests protect and unprotect, you must create a scheme policy that grants these permissions to the user. See Create Scheme Policies on PrivaceraCloud.

Anatomy of a PEG API Request on PrivaceraCloud#

This example of the /protect request illustrates some common fields of the PEG REST API on PrivaceraCloud. The example is split across separate lines for clarity but in actual use is a single line.

curl 
--request POST https://<cloud_peg_api_endpoint>/api/<api_key>/api/peg/public/protect
-u <service_user>:<password>
--header Accept: application/json
--header Content-Type: application/json'
--data-raw {"schemelist":["<encryption_scheme>"],
     "datalist":[["<data>",...]],
     "user":"<application_user>"}'
  • <cloud_peg_api_endpoint>: Your own API endpoint, as described in PEG API Endpoint.
  • <api_key>: Your API key, as described in API Key.
  • <scheme>: The /protect request includes a field to specify a required encryption scheme. The server uses the schemelist to encrypt the data. See Encryption Schemes.
  • presentationSchemeList: Not shown here, the /unprotect request can include a field to specify an optional presentation scheme. On /unprotect, the server uses the presentation_scheme to obfuscate the data even more for display to authorized users. See Presentation Schemes. presentationSchemeList on /protect is ignored.
  • <application_user>: The application user or end-user that connects to a service, such as Snowflake, UDF, or ODBC application.
  • <data>: The objects the request operates on. This is a JSON array that you must construct.
  • callingUser: Some older versions of the PEG REST API included a callingUser field, which is not shown here. This field is not required and if present is ignored.
  • <cloud_peg_api_endpoint>/api: The endpoint of the PEG service for PrivaceraCloud. <tenant-id> is part of the URL displayed in the portal. See PEG API Endpoint.

About Constructing the datalist for /protect#

Suppose you want to encrypt two database fields tagged with Privacera metadata PERSON_NAME and EMAIL. The value of your API datalist to encrypt can be constructed like this:

  1. Extract from the database the unencrypted values of the tagged fields.
  2. Format a JSON array of those values.
  3. Make an API /protect request to encrypt the values in that array.
  4. Reformat the returned JSON array of the encrypted values to update the fields in your database.

About Deconstructing the Response from /unprotect#

Suppose you want to decrypt two database fields tagged with Privacera metadata PERSON_NAME and EMAIL. The value of your API datalist to decrypt can be constructed like this:

  1. Extract from the database the encrypted values of the tagged fields.
  2. Format a JSON array of those values.
  3. Make an API /unprotect request to decrypt the values in that array.
  4. Reformat the returned JSON array of the decrypted values to update the fields in your database.

Example PEG REST API Requests for PrivaceraCloud#

These examples use the Linux line continuation character \.

If you are testing with a self-signed certificate, to bypass the certificate validation check, add the curl -k option.

/protect#

The two elements in the input datalist array are encrypted with the encryption schemes PERSON_NAME and EMAIL.

curl -u <service_user>:<password> \
--request POST https://<cloud_peg_api_endpoint>/api/<api_key>/api/peg/public/protect'
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data-raw {"schemelist":["PERSON_NAME", "EMAIL"], \
           "datalist": [["Mark","Jonathan","Christopher"], ["mark@example.com","jonathan@test.com","christopher@google.com"]], \
           "user":"<application_user>"} 

Response

"datalist": [["WjM5","5vpJF9zT","1EbplEYVBjy"],["i0bD@WKbMYpr.CvE","?9aqS8zV@YUym.hkd","d501shhJEO&@YpvfOc.VYH"]]

/unprotect#

The two elements in the input datalist array are decrypted with the encryption schemes PERSON_NAME and EMAIL.

curl \
--request POST https://<cloud_peg_api_endpoint>/api/<api_key>/api/peg/public/unprotect \
--header Content-Type: application/json \
--header Accept: application/json \
--data-raw {"schemelist":["PERSON_NAME", "EMAIL"], \
           "datalist": [["WjM5","5vpJF9zT","1EbplEYVBjy"],["i0bD@WKbMYpr.CvE","?9aqS8zV@YUym.hkd","d501shhJEO&@YpvfOc.VYH"]], \
           "user":"<application_user>"} 

Response

"datalist": [["Mark","Jonathan","Christopher"], ["mark@example.com","jonathan@test.com","christopher@google.com"]]

/unprotect with Presentation Scheme#

The input in the datalist array is decrypted with the encryption scheme EMAIL2 and then obfuscated with the presentation scheme EMAIL2_P.

curl \
--request POST https://<cloud_peg_api_endpoint>/api/<api_key>/api/peg/public/unprotect \
--header "Accept: application/json" \
--header Content-Type: application/json \
--data-raw {"datalist":[["8283a@QhbpH.yOs","5fGP@RyZBO.UZE"]], \
           "schemelist":["EMAIL2"], \
           "presentationSchemelist":["EMAIL2_P"] \
           "user":"<application_user>"}'

Audit Details for PEG REST API Accesses#

PrivaceraCloud records access to the PEG REST API encryption keys and schemes. For details, Audits.


Last update: October 5, 2021