Skip to content

PEG REST API on Privacera Platform

PEG API Endpoint#

For the 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.

Endpoint Summary for Privacera Platform#

The PEG REST API consists of the following endpoints:

  • /authenticate - Generates a token to be used with subsequent /protect and /unprotect endpoints.
  • /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 endpoint

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

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 endpoints in the following form: 

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

Get Token with /authenticate endpoint#

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

  1. The client uses the /authenticate endpoint 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 Endpoint 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 calls to /protect and /unprotect endpoints must include the X-API-KEY header with the token.

    X-API-KEY:<token_from_authenticate>;

Anatomy of a PEG API Endpoint on Privacera Platform#

This example of the /protect endpoint illustrates some common fields of the PEG REST API on the 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 for protect and About Deconstructing the datalist for unprotect.
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 datalist for 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 of Data Transformation with /unprotect and Presentation Scheme#

This example shows some original input data, its representation when encrypted, and its obfuscated result after decryption with /unprotect and an optional presentation scheme, as shown in /unprotect with Presentation Scheme.

  • Original value: sally@gmail.com
  • Encrypted value: xy12zb@1mno2.rtz
  • Value after decryption and presentation scheme. The domain portion has been obfuscated: sally@ymxof.1dg

Example PEG API Endpoints 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"}'

REST API Response Partial Success on Bulk Operations#

For bulk operations, in which multiple data elements are included in the datalist JSON array of the /protect or /unprotect request, if an error is encountered in processing one of those elements, the endpoint returns the response as "Partial Success" but does not fail the entire batch.

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.