Skip to content

PEG REST API on Privacera Platform

PEG API Endpoint#

For the standalone Privacera Platform, by default, the PEG API endpoint is:

https://<privacera_hostname>:6869/api/peg/public

Check with your installation team for the value of <privacera_hostname> and if they have changed this default port.

Request Summary for Privacera Platform#

The PEG REST API consists of the following requests:

  • /authenticate - Generates a token to be used with subsequent /protect and /unprotect requests.
  • /getSchemes - Returns the names of Privacera-supplied and user-defined encryption schemes.
  • /protect - Encrypts the data.
  • /unprotect - Decrypts the data.

Authentication Methods on Privacera Platform#

There are two different ways to authenticate to the PEG REST API:

  • Basic authentication with username and password.
  • An authentication token.

Basic Authentication#

A Portal user needs to have the ROLE_ENCRYPTION_ALL or ROLE_ENCRYPTION_READ role to authenticate to the PEG REST API via basic authentication.

For details on assigning roles, see User Management.

Authentication Token#

The PEG REST API authentication token can be created in two ways:

  • In the Privacera Portal
  • With the /authenticate REST API request.

The token must be included in the HTTP header of subsequent requests.

The token has a configurable validity period. See Add Keytab Expiry Date.

Generate Token in Privacera Portal#

The token can be generated in the Portal as follows:

  1. Login to the Privacera Portal.

  2. From the left navigation menu, select Launch Pad and click Privacera Token.

  3. Click +Generate Token and generate a new token after you enter the expiration details, etc.

  4. The components of the token, an Access Key and a Secret Key, are generated as shown in the example below:

    <img src="../assets/image10" style="width:100%;height:auto" />

  5. Store the Access Key and Secret Key credentials safely.  

The token is a combination of <AccessKey and SecretKey> delimited by a colon (:): <AccessKey:SecretKey>.

It is required in the header of the /protect or /unprotect requests in the following form:

X-API-KEY:<AccessKey>:<SecretKey>

Get Token with /authenticate request#

The token is generated with the /authenticate request as follows:

  1. The client makes an /authenticate request with basic authentication user credentials to authenticate the end-user.  PEG is integrated with the Privacera Portal. For definitions of <service_user> and <application_user>, see Anatomy of a PEG API Request on Privacera Platform.

    curl -u <service_user>:<password> \
         --header "Accept: application/json" \
         --header "Content-Type: application/json" \
         --data-raw '"user":"<application_user>"' \
            https://<privacera_hostname>:6869/api/peg/public/authenticate
    
  2. If the authentication is successful, the PEG returns the colon-delimited token <AccessKey>:<SecretKey>.

  3. Subsequent /protect and /unprotect requests must include the X-API-KEY header with the token.

    X-API-KEY:<token_from_authenticate>;
    

Anatomy of a PEG API Request on Privacera Platform#

This example of the /protect request illustrates some common fields of the PEG REST API on the standalone Privacera Platform.

Instead of basic authentication, this example uses token authentication with a X-API-KEY:<token_from_authenticate>. If you want basic authentication, remove the token line in this example and replace it with -u <service_user>:<password>.

curl \
--request 'POST https://<privacera_hostname>:6869/api/peg/public/protect'
--header "X-API-KEY:<token_from_authenticate>" \
--header "Accept: application/json" \
--header 'Content-Type: application/json' \
--data-raw '{"schemelist":["<encryption_scheme>"], \
     "datalist":[["<data>",...]], \
     "user":"<application_user>"}'
Line Description
<token_from_authenticate> The /authenticate request (detailed in Authentication Token) returns a token that must be prepended with X-API-KEY and included in the header of subsequent requests.
If this anatomy showed basic authentication, it would use the curl option -u <service_user>:<password>:
  • <service_user>: The user issuing the API request. This user is authenticated by Privacera. Examples include Lambda functions servicing Snowflake or UDFs servicing end users. The <service_user> must have the administrative role (ROLE_ADMIN). to be able to issue the /protect and /unprotect requests on behalf of the <application_user>.
  • <password>: The service_user's password.
<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. See About Constructing the datalist.
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.
https://<privacera_hostname>:6869/api/peg/public The PEG API endpoint and default port for Privacera Platform.

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 API Requests on Privacera Platform#

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.

/authenticate#

As required for /authenticate, this example uses basic authentication to retrieve a token that is used in the other examples.

curl \
-u <service_user>:<password> \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '"user":"<application_user>"' \
https://privacera.com:6869/api/peg/public/authenticate 

Response

{"token":"bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk","tokenid":1,"tokenExpiry":"2021-04-01T12:19:30Z","tokenName":"service_user",tokenStatus":"ENABLED",userName":"application_user"}

/protect#

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

This example uses the authentication token retrieved with /authenticate`.

curl  \
--request 'POST https://privacera.BigCo.com:6869/api/peg/public/protect'
--header "X-API-KEY: bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk" \
--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":"jimmybob@BigCo.com"}' 

Response

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

/unprotect#

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

This example uses the authentication token retrieved with /authenticate.

curl \
--request 'POST https://privacera.compliance.BigCo.com:6869/api/peg/public/unprotect' \
--header 'X-API-KEY: bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk' \
--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"]],"data":"","responseStatus":"SUCCESS"}

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

This example uses the authentication token retrieved with /authenticate.

curl \
--request 'POST https://privacera.BigCo.com:6869/api/peg/public/unprotect' \
--header 'X-API-KEY: bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk' \
--header "Accept: application/json" \
--header 'Content-Type: application/json' \
--data-raw '{"datalist":[["8283a@QhbpH.yOs","5fGP@RyZBO.UZE"]], \
           "schemelist":["EMAIL2"], \
           "presentationSchemelist":["EMAIL2_P"] \
           "user":"jimmybob@BigCo.com"}'

Audit Details for PEG REST API Accesses#

Privacera records access to the PEG REST API encryption keys and schemes. For details, Audit.

REST API Reference#

See REST API Documentation for Portal API and PEG API.


Last update: July 23, 2021