This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Private Endpoints

Endpoints dedicated to running PoCs

This section documents private endpoints made available on the Protegrity API Playground. The private endpoints are the low-level APIs that closely resemble the product’s functionality. The endpoints allow for more flexibility and customization than the rest of the set. There are no performance limitations imposed (other than the network lag).

Access the endpoints can be requested through your Protegrity contact (Sales Engineer, Field Engineer, or Customer Success Manager). Running the endpoints requires an additional authentication key that will be set up specifically for your organization and project.

1 - Data Protection Endpoint

De-identify sensitive data

METHOD: POST

ENDPOINT: https://api.playground.protegrity.com/v1/private/protect

DESCRIPTION:

Protect any data. Specify the data element and user name to apply during the transformation.

ATTRIBUTES:

data (required) Input data to transform.

data_element (required) Data element to apply when transforming data. Consult the Policy Definition section for the list of supported data elements and their characteristics.

user (required) Choose a user to impersonate from the list of pre-configured roles.

encoding (optional) Type of encoding used for input (and output) data. Note that all encodings are supported for all data elements with the exception of utf8 that cannot be used with encryption data elements. Accepts: [ hex | base64 | utf8 ]. Defaults to utf8.

external_iv (optional) Provide your custom initialization vector to introduce additional variance in the output. The IV may be a number, letter, special character, or a combination of those. Learn more about the IVs in the Key Concepts section. Note that to unprotect the data back to its original value, the external_iv has to be provided in the payload.

SAMPLE REQUEST 

curl --location 'https://api.playground.protegrity.com/v1/private/protect' \
--header 'x-api-key: <Group_API_Key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <JWT_TOKEN>' \
--data '{
    "encoding": "utf8",
    "data_element": "city",
    "user": "admin",
    "data": ["Phoenix"],
    "external_iv": "eiv1"
}'
  
import requests
import json

JWT_Token = "<JWT_TOKEN>"
API_Key = "<Group_API_Key>"
url = 'https://api.playground.protegrity.com/v1/private/protect' 
headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token } 
data = {
  "encoding": "utf8",
  "data_element": "city",
  "user": "admin",
  "data": [
    "Phoenix"
  ],
  "external_iv": "eiv1"
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.text)

  
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL; 
import java.io.OutputStream; 
import java.io.InputStreamReader; 
import java.io.BufferedReader;

public class APIRequest { public static void main(String[] args) { 
  try { 
    String JWT_Token = "<JWT_TOKEN>"
    String API_Key = "<Group_API_Key>"
    URI uri = new URI("https://api.playground.protegrity.com/v1/private/protect");
    URL url = uri.toURL(); 
    HttpURLConnection conn = (HttpURLConnection) url.openConnection(); 
    conn.setRequestMethod("POST"); 
    conn.setRequestProperty("x-api-key", API_Key); 
    conn.setRequestProperty("Content-Type", "application/json"); 
    conn.setRequestProperty("Authorization", JWT_Token); conn.setDoOutput(true);

    String jsonInputString = "{ \"encoding\": \"utf8\",\"data_element\": \"city\",\"user\": \"admin\",\"data\": [\"Phoenix\"],\"external_iv\": \"eiv1\" }";
    
    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = jsonInputString.getBytes("utf-8");
        os.write(input, 0, input.length);
    }

    try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"))) {
        StringBuilder response = new StringBuilder();
        String responseLine = null;
        while ((responseLine = br.readLine()) != null) {
            response.append(responseLine.trim());
        }
        System.out.println(response.toString());
    }

    } catch (Exception e) {
        e.printStackTrace();
    }
}
}
  
fetch('https://api.playground.protegrity.com/v1/private/protect', 
    { method: 'POST', 
      headers: { 'x-api-key': '<Group_API_Key>', 'Content-Type': 'application/json', 'Authorization': '<JWT_TOKEN>' }, 
      body: JSON.stringify({ 
        "encoding": "utf8",
        "data_element": "city",
        "user": "admin",
        "data": [
          "Phoenix"
        ],
        "external_iv": "eiv1" 
        }) 
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error)); 

 

package main

import ( 
	"io" 
	"fmt"
	"strings" 
	"net/http" 
  )
  
func main() { 
	JWT_Token := "<JWT_TOKEN>"
	API_Key := "<Group_API_Key>"
	url := "https://api.playground.protegrity.com/v1/private/protect" 
	data := strings.NewReader(`{ 
      "encoding": "utf8",
      "data_element": "city",
      "user": "admin",
      "data": ["Phoenix"],
      "external_iv": "eiv1"
    }`) 
  
	req, err := http.NewRequest("POST", url, data)
	if err != nil {
		fmt.Println(err)
		return
	}
  
	req.Header.Set("x-api-key", API_Key)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", JWT_Token)
  
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
  

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(string(body))
}

SAMPLE RESPONSE 


{
  "encoding": "utf8",
  "results": [
    "oULqaPc"
  ],
  "success": true
}

2 - Data Unprotection Endpoint

Re-identify previously protected data

METHOD: POST

ENDPOINT: https://api.playground.protegrity.com/v1/private/unprotect

DESCRIPTION:

Unprotect previously de-identified data, i.e. reverse it to its original state and clear any transformations. Specify the data element and user name to apply during the transformation.

ATTRIBUTES:

data (required) Input data to transform.

data_element (required) Data element to apply when transforming data. Consult the Policy Definition section for the list of supported data elements and their characteristics.

user (required) Choose a user to impersonate from the list of pre-configured roles.

encoding (optional) Type of encoding used for input (and output) data. Note that all encodings are supported for all data elements with the exception of utf8 that cannot be used with encryption data elements. Accepts: [ hex | base64 | utf8 ]. Defaults to utf8.

external_iv (optional) Provide the custom initialization vector used to protect the data. Learn more about the IVs in the Key Concepts section.

SAMPLE REQUEST 

curl --location 'https://api.playground.protegrity.com/v1/private/unprotect' \
--header 'x-api-key: <Group_API_Key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <JWT_TOKEN>' \
--data '{
    "encoding": "utf8",
    "data_element": "city",
    "user": "admin",
    "data": ["oULqaPc"],
    "external_iv": "eiv1"
}'
  
import requests
import json

JWT_Token = "<JWT_TOKEN>"
API_Key = "<Group_API_Key>"
url = 'https://api.playground.protegrity.com/v1/private/unprotect' 
headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token } 
data = {
  "encoding": "utf8",
  "data_element": "city",
  "user": "admin",
  "data": [
    "oULqaPc"
  ],
  "external_iv": "eiv1"
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.text)

  
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL; 
import java.io.OutputStream; 
import java.io.InputStreamReader; 
import java.io.BufferedReader;

public class APIRequest { public static void main(String[] args) { 
  try { 
    String JWT_Token = "<JWT_TOKEN>"
    String API_Key = "<Group_API_Key>"
    URI uri = new URI("https://api.playground.protegrity.com/v1/private/unprotect");
    URL url = uri.toURL(); 
    HttpURLConnection conn = (HttpURLConnection) url.openConnection(); 
    conn.setRequestMethod("POST"); 
    conn.setRequestProperty("x-api-key", API_Key); 
    conn.setRequestProperty("Content-Type", "application/json"); 
    conn.setRequestProperty("Authorization", JWT_Token); conn.setDoOutput(true);

    String jsonInputString = "{ \"encoding\": \"utf8\",\"data_element\": \"city\",\"user\": \"admin\",\"data\": [\"oULqaPc\"],\"external_iv\": \"eiv1\" }";
    
    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = jsonInputString.getBytes("utf-8");
        os.write(input, 0, input.length);
    }

    try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"))) {
        StringBuilder response = new StringBuilder();
        String responseLine = null;
        while ((responseLine = br.readLine()) != null) {
            response.append(responseLine.trim());
        }
        System.out.println(response.toString());
    }

    } catch (Exception e) {
        e.printStackTrace();
    }
}
}
  
fetch('https://api.playground.protegrity.com/v1/private/unprotect', 
    { method: 'POST', 
      headers: { 'x-api-key': '<Group_API_Key>', 'Content-Type': 'application/json', 'Authorization': '<JWT_TOKEN>' }, 
      body: JSON.stringify({ 
        "encoding": "utf8",
        "data_element": "city",
        "user": "admin",
        "data": [
          "oULqaPc"
        ],
        "external_iv": "eiv1" 
        }) 
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error)); 

 

package main

import ( 
	"io" 
	"fmt"
	"strings" 
	"net/http" 
  )
  
func main() { 
	JWT_Token := "<JWT_TOKEN>"
	API_Key := "<Group_API_Key>"
	url := "https://api.playground.protegrity.com/v1/private/unprotect" 
	data := strings.NewReader(`{ 
      "encoding": "utf8",
      "data_element": "city",
      "user": "admin",
      "data": ["oULqaPc"],
      "external_iv": "eiv1"
    }`) 
  
	req, err := http.NewRequest("POST", url, data)
	if err != nil {
		fmt.Println(err)
		return
	}
  
	req.Header.Set("x-api-key", API_Key)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", JWT_Token)
  
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
  

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(string(body))
}

SAMPLE RESPONSE 


{
  "encoding": "utf8",
  "results": [
    "Phoenix"
  ],
  "success": true
}

3 - Nesting Requests

Adding structure to your requests

You can pass multiple payloads within your request to the protect and unprotect endpoints, mixing together data formats and transformation types. In order to do that, your requests need to be structured in the following manner:

TOP LEVEL ATTRIBUTES

user (required) Choose a user to impersonate from the list of pre-configured roles.

arguments (optional) A nesting element used for passing multiple protection requests as an array.

NESTED ATTRIBUTES

The following attributes have to be provided for every payload sent:

id (optional) ID or label of a single for logging purposes. It will be appended to the query_id field.

data (required) Input data to transform.

data_element (required) Data element to apply when transforming data. Consult the Policy Definition section for the list of supported data elements and their characteristics.

encoding (optional) Type of encoding used for input (and output) data. Note that all encodings are supported for all data elements with the exception of utf8 that cannot be used with encryption data elements. Accepts: [ hex | base64 | utf8 ]. Defaults to utf8.

external_iv (optional) Provide your custom initialization vector to introduce additional variance in the output. The IV may be a number, letter, special character, or a combination of those. Learn more about the IVs in the Key Concepts section. Note that to unprotect the data back to its original value, the external_iv has to be provided in the payload.

SAMPLE REQUEST 

curl --location 'https://api.playground.protegrity.com/v1/private/protect' \
--header 'x-api-key: <Group_API_Key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <JWT_TOKEN>' \
--data '{
    "user": "admin",
    "arguments": [
        {
            "id": "id1",
            "data_element": "city",
            "data": [
                "Phoenix"
            ]
        },
        {
            "external_iv": "LOB_1",
            "data_element": "name",
            "data": [
                "Ava O’Connor",
                "Peregrine Wojcik"
            ]
        }
    ]
}'
  
import requests
import json

JWT_Token = "<JWT_TOKEN>"
API_Key = "<Group_API_Key>"
url = 'https://api.playground.protegrity.com/v1/private/protect' 
headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token } 
data = {
  "user": "admin",
  "arguments": [
    {
      "id": "id1",
      "data_element": "city",
      "data": [
        "Phoenix"
      ]
    },
    {
      "external_iv": "LOB_1",
      "data_element": "name",
      "data": [
        "Ava O’Connor",
        "Peregrine Wojcik"
      ]
    }
  ]
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.text)

  
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL; 
import java.io.OutputStream; 
import java.io.InputStreamReader; 
import java.io.BufferedReader;

public class APIRequest { public static void main(String[] args) { 
  try { 
    String JWT_Token = "<JWT_TOKEN>"
    String API_Key = "<Group_API_Key>"
    URI uri = new URI("https://api.playground.protegrity.com/v1/private/protect");
    URL url = uri.toURL(); 
    HttpURLConnection conn = (HttpURLConnection) url.openConnection(); 
    conn.setRequestMethod("POST"); 
    conn.setRequestProperty("x-api-key", API_Key); 
    conn.setRequestProperty("Content-Type", "application/json"); 
    conn.setRequestProperty("Authorization", JWT_Token); conn.setDoOutput(true);

    String jsonInputString = "\"user\": \"admin\",\"arguments\": {\"id\": \"id1\",\"data_element\": \"city\",\"data\": [    \"Phoenix\"]},{\"external_iv\": \"LOB_1\",\"data_element\": \"name\",\"data\": [\"Ava O’Connor\",\"Peregrine Wojcik\"]}";
    
    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = jsonInputString.getBytes("utf-8");
        os.write(input, 0, input.length);
    }

    try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"))) {
        StringBuilder response = new StringBuilder();
        String responseLine = null;
        while ((responseLine = br.readLine()) != null) {
            response.append(responseLine.trim());
        }
        System.out.println(response.toString());
    }

    } catch (Exception e) {
        e.printStackTrace();
    }
}
}
  
fetch('https://api.playground.protegrity.com/v1/private/protect', 
    { method: 'POST', 
      headers: { 'x-api-key': '<Group_API_Key>', 'Content-Type': 'application/json', 'Authorization': '<JWT_TOKEN>' }, 
      body: JSON.stringify({
        "user": "admin",
        "arguments": [
          {
            "id": "id1",
            "data_element": "city",
            "data": [
              "Phoenix"
            ]
          },
          {
            "external_iv": "LOB_1",
            "data_element": "name",
            "data": [
              "Ava O’Connor",
              "Peregrine Wojcik"
            ]
          }
        ]
      })
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error)); 

 

package main

import ( 
	"io" 
	"fmt"
	"strings" 
	"net/http" 
  )
  
func main() { 
	JWT_Token := "<JWT_TOKEN>"
	API_Key := "<Group_API_Key>"
	url := "https://api.playground.protegrity.com/v1/private/protect" 
	data := strings.NewReader(`{ 
      "user": "admin",
      "arguments": [
          {
              "id": "id1",
              "data_element": "city",
              "data": [
                  "Phoenix"
              ]
          },
          {
              "external_iv": "LOB_1",
              "data_element": "name",
              "data": [
                  "Ava O’Connor",
                  "Peregrine Wojcik"
              ]
          }
      ]
    }`) 
  
	req, err := http.NewRequest("POST", url, data)
	if err != nil {
		fmt.Println(err)
		return
	}
  
	req.Header.Set("x-api-key", API_Key)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", JWT_Token)
  
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
  

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(string(body))
}

SAMPLE RESPONSE 


{
    "results": [
        {
            "encoding": "utf8",
            "id": "id1",
            "results": [
                "pGPtJxg"
            ],
            "success": true
        },
        {
            "encoding": "utf8",
            "results": [
                "otO D’vawbCO",
                "JKWTkOMDK zPAgFlO"
            ],
            "success": true
        }
    ],
    "success": true
}

4 - Data Security Policy

Data Security Policy configuration

This section describes the Policy configuration used by the API Playground. All listed data elements can be used when calling the private endpoints.

Policy Definition

Generic Data Elements

Data Element Method Use Case UTF Set LP PP eIV Role
Admin Finance Marketing HR
P U P U P U P U
datetime Tokenization A date or datetime string. Formats accepted: YYYY/MM/DD HH:MM:SS and YYYY/MM/DD. Delimiters accepted: /, - (required). N/A N/A N/A No ✓ Ｘ Ｘ Ｘ Ｘ ✓ Ｘ Ｘ
datetime_yc Tokenization A date or datetime string. Formats accepted: YYYY/MM/DD HH:MM:SS and YYYY/MM/DD. Delimiters accepted: /, - (required). Leaves the year in the clear. N/A N/A N/A No ✓ Ｘ Ｘ Ｘ Ｘ ✓ Ｘ Ｘ
int Tokenization An integer string (4 bytes). Numeric No No Yes ✓ Ｘ Ｘ Ｘ Ｘ ✓ Ｘ Ｘ
number Tokenization A numeric string. May produce leading zeroes. Numeric No No Yes ✓ Ｘ Ｘ Ｘ Ｘ ✓ Ｘ Ｘ
string Tokenization An alphanumeric string. Latin + Numeric No No Yes ✓ Ｘ Ｘ Ｘ Ｘ ✓ Ｘ Ｘ
long_text Encryption A long string (e.g., a comment field) using any character set. Use hex or base64 encoding to utilize. All No No Yes ✓ Ｘ Ｘ Ｘ Ｘ ✓ Ｘ Ｘ

PCI DSS Data Elements

Data Element Method Use Case UTF Set LP PP eIV Role
Admin Finance Marketing HR
P U P U P U P U
ccn Tokenization Credit card numbers. Numeric No No Yes ✓ Ｘ Ｘ ✓ Ｘ X Ｘ Ｘ
ccn_bin Tokenization Credit card numbers. Leaves 8-digit BIN in the clear. Numeric No No Yes ✓ Ｘ Ｘ ✓ Ｘ X Ｘ Ｘ
iban Tokenization IBAN numbers. Preserves the length, case, and position of the input characters but may create invalid IBAN codes. Latin + Numeric Yes Yes No ✓ Ｘ Ｘ ✓ Ｘ X Ｘ Ｘ
iban_cc Tokenization IBAN numbers. Leaves letters in the clear. Latin + Numeric Yes Yes Yes ✓ Ｘ Ｘ ✓ Ｘ X Ｘ Ｘ

PII Data Elements

Data Element Method Use Case UTF Set LP PP eIV Role
Admin Finance Marketing HR
P U P U P U P U
address Tokenization Street names Latin + Numeric No No Yes ✓ Ｘ Ｘ ✓ Ｘ Ｘ Ｘ ✓
city Tokenization Town or city name Latin No No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
dob Tokenization A date string. Formats accepted: YYYY/MM/DD and YYYY/MM/DD. Delimiters accepted: /, - (required). N/A N/A No No ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
dob_yc Tokenization A date string. Formats accepted: YYYY/MM/DD and YYYY/MM/DD. Delimiters accepted: /, - (required). Leaves the year in the clear. N/A N/A No No ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
email Tokenization Email address. Leaves the domain in the clear. Latin + Numeric No No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
nin Tokenization National Insurance Number. Preserves the length, case, and position of the input characters but may create invalid NIN codes. Latin + Numeric Yes Yes No ✓ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ
name Tokenization Person's name Latin No No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
passport Tokenization Passport codes. Preserves the length, case, and position of the input characters but may create invalid passport numbers. Latin + Numeric Yes Yes No ✓ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ
phone Tokenization Phone number. May produce leading zeroes. Latin + Numeric Yes No Yes ✓ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ
postcode Tokenization Postal codes with digits and characters. Preserves the length, case, and position of the input characters but may create invalid post codes. Latin + numeric Yes Yes No ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
ssn Tokenization Social Security Number (US) Latin + Numeric Yes No Yes ✓ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ Ｘ
zipcode Tokenization Zip codes with digits only. May produce leading zeroes. Numeric Yes No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓

PII Data Elements

Data Element Method Use Case UTF Set LP PP eIV Role
Admin Finance Marketing HR
P U P U P U P U
address_de Tokenization Street names (German) Latin + German + Numeric No No Yes ✓ Ｘ Ｘ ✓ Ｘ Ｘ Ｘ ✓
address_fr Tokenization Street names (French) Latin + French + Numeric No No Yes ✓ Ｘ Ｘ ✓ Ｘ Ｘ Ｘ ✓
city_de Tokenization Town or city name (German) Latin + German No No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
city_fr Tokenization Town or city name (French) Latin + French No No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
name_de Tokenization Person's name (German) Latin + German No No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓
name_fr Tokenization Person's name (French) Latin + French No No Yes ✓ Ｘ Ｘ ✓ Ｘ ✓ Ｘ ✓

LEGEND

  • eIV External IV
  • LP Length Preservation
  • PP Position Preservation
  • P User group can protect data
  • U User group can unprotect data