Protegrity API Playground features functionality derived from the original suite of Protegrity products in a form of API calls. Our API endpoints are easy-to-use and ask for minimal configuration. The Playground divides available endpoint portfolio into the following families:
Data Protection endpoints, covering sensitive data protection. Users can decide to transform various data types, from numbers, strings, and dates without any inherent logic tom specific PII attributes like postcodes, or social security numbers.
GenAI Security endpoints that combine the capabilities of the above, allowing users to perform automatic discovery and protection of sensitive data and specify their risk tolerance.
Private endpoints low-level APIs that are the closest to the actual product experience, allowing for high customization. We suggest using the private endpoints for conducting PoCs in house – with Protegrity’s Professional Services guidance. The endpoints are disabled to all users by default and are available upon request only.
Note: Protegrity does not store any data received from external API requests.
Watch the video below to learn how to use the API Playground:
1 - Usage & Limitations
Limits of the API
To ensure fair use of the API service, we enforce rate limits on API requests.
These limits are:
Request Rate: 50 per second
Burst: up to 100
Quota: 10,000 requests per user
Max. Payload Size: 1MB
The same limits do not apply when using the Private endpoints.
Note: Users are removed from the platform after 30 days of inactivity.
2 - Required Headers
Required authentication headers
Every request should carry the following headers:
x-api-key(required): Your unique API Key. Received after a successful sign-up.
Authorization(required): A JWT token for the session. Obtained by running the Login and Change Password endpoints.
Content-Type(required): Set to application/json.
3 - Users and Roles
Built-in users and roles to impersonate
To add additional flavor to your testing activities, you can now leverage any of the preconfigured users to showcase Protegrity’s Role-Based Access Controls. Using a diffierent user will result in distinct views over sensitive data. Some users will only be able to protect data but will not be able to reverse the operation. Some users will only be able to re-identify selected attributes.
To use any of the roles, simply pass your chosen value to the payload in the user attribute during the protect or unprotect operation. If the user is not specified, the request will default to superuser.
Available Roles
The following roles and users have been configured and are available for use:
ADMIN:
admin or devops or jay.banerjee The role can protect all data but cannot unprotect. Upon an unprotection attempt they will be displayed protected values.
FINANCE:
finance or robin.goodwill The role can unprotect all PII and PCI data. The role cannot protect any data. When attempting to unprotect data without authorization, they will be displayed nulls.
MARKETING:
marketing or merlin.ishida The role can unprotect some PII data that is required for analytical research and campaign outreach. When attempting to unprotect data without authorization, they will be displayed nulls. The role cannot protect any data.
HR:
hr or paloma.torres The role can unprotect all PII data but cannot view any PCI data. When attempting to unprotect data without authorization, they will be displayed nulls. The role cannot protect any data.
OTHER:
superuser The role can perform any protect and unprotect operation. The role has been made available for testing only – we strongly advise against creating superuser roles in your environments.
Additionally, you may type in any user name to simulate unauthorized user behavior.
4 - Sensitive Data Discovery Endpoints
Detecting sensitive information
Sensitive data discovery is a cornerstone of any data-centric security initiative: it helps understand whether any sensitive data resides at rest, or it is present within ETL pipelines or elsewhere in-transit. The API Playground exposes REST endpoint that can be used to identify sensitive data within received payloads.
Detect and classify sensitive data in a given input. The endpoint will return a classification and confidence score for every sensitive attribute found, alongside its location – a column name or a start and end index. Confidence score returns values from 0.1 to 1. The higher the confidence score, the more the product is sure of the PII classification it produced. We recommend using the confidence score to prioritize inspection of found sensitive data.
ATTRIBUTES:
data(required) Input data to transform.
OPTIONS:
format(required) Specify the format of the input data. Option text covers unstructured text. Option csv is used for processing comma-separated values. Accepts: [ text | csv ].
header_line(optional) Specific to csv content only. Set to true if the data includes a header line in the first row. Set to false in case of the opposite. Accepts: [ true | false ]. Defaults to false.
raw(optional) Returns verbose output of the classification job when set to true. Accepts: [ true | false ]. Defaults to false.
SAMPLE REQUEST – TEXT
curl --location 'https://api.playground.protegrity.com/v1/discover'\
--header 'x-api-key: <API_Key>'\
--header 'Content-Type: application/json'\
--header 'Authorization: <JWT_TOKEN>'\
--data '{
"options": {
"format": "text",
"raw": false
},
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}'
import requests
import json
JWT_Token ="<JWT_TOKEN>"API_Key ="<API_Key>"url ='https://api.playground.protegrity.com/v1/discover'headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token }
data = {
"options": {
"format": "text",
"raw": "false" },
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}
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;
publicclassAPIRequest { publicstaticvoidmain(String[] args) {
try {
String JWT_Token ="<JWT_TOKEN>" String API_Key ="<API_Key>" URI uri =new URI("https://api.playground.protegrity.com/v1/discover");
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 ="{ \"options\": {\n"+//" \"format\": \"text\",\n"+//" \"raw\": false\n"+//" },\n"+//" \"data\": [\"Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!\"]\n"+//" }";
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/discover',
{ method:'POST',
headers: { 'x-api-key':'<API_Key>', 'Content-Type':'application/json', 'Authorization':'<JWT_TOKEN>' },
body:JSON.stringify({
"options": {
"format":"text",
"raw":false },
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
packagemainimport (
"io""fmt""strings""net/http" )
funcmain() {
JWT_Token:="<JWT_TOKEN>"API_Key:="<API_Key>"url:="https://api.playground.protegrity.com/v1/discover"data:=strings.NewReader(`{
"options": {
"format": "text",
"raw": false
},
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}`)
req, err:=http.NewRequest("POST", url, data)
iferr!=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)
iferr!=nil {
fmt.Println(err)
return }
deferresp.Body.Close()
body, err:=io.ReadAll(resp.Body)
iferr!=nil {
fmt.Println(err)
return }
fmt.Println(string(body))
}
Protecting names, addresses, and other PII information
Protegrity API Playground exposes a curated selection of endpoints for data protection: you can use them to secure any PII and PCI information. The predefined endpoints include names, addresses, numbers, Credit Card Numbers, Social Security Numbers, and more. Format, length and language preservation are supported.
This collection is a subset of Protegrity functions available in the full version of the product.
Protect or unprotect a person’s name. The received token is not length-preserving.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
dictionary(optional) Specify the Unicode domain of the input and output values. Option en covers all characters within the Basic Latin block of the Unicode standard (range U+0000..U+007F). Options de and fr extend that coverage to include German and French characters, respectively. Accepts: [ en | de | fr ]. Defaults to en.
eiv(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 eiv has to be provided in the payload.
Protect or unprotect an address. The received token is not length-preserving.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
dictionary(optional) Specify the Unicode domain of the input and output values. Option en covers all characters within the Basic Latin block of the Unicode standard (range U+0000..U+007F). Options de and fr extend that coverage to include German and French characters, respectively. Accepts: [ en | de | fr ]. Defaults to en.
eiv(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 eiv has to be provided in the payload.
SAMPLE REQUEST
curl --location 'https://api.playground.protegrity.com/v1/address'--header 'x-api-key: <API_Key>'--header 'Content-Type: application/json'--header 'Authorization: <JWT_TOKEN>'--data '{
"operation": "protect",
"data": ["77 Boulevard Saint-Jacques", "46 avenue de la Grande Armée"],
"options": {
"dictionary": "fr"
}
}'
Protect or unprotect a town or city. The received token is not length-preserving.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
dictionary(optional) Specify the Unicode domain of the input and output values. Option en covers all characters within the Basic Latin block of the Unicode standard (range U+0000..U+007F). Options de and fr extend that coverage to include German and French characters, respectively. Accepts: [ en | de | fr ]. Defaults to en.
eiv(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 eiv has to be provided in the payload.
Protect or unprotect a postal code with digits and chatacters. The received token is case-, length-, and position-preserving but may create invalid postal codes (e.g., restricted letters).
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
Protect or unprotect a postal code with digits only. The received token is length-preserving. The method may produce leading zeroes and invalid zipcodes (e.g., restricted digits).
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
eiv(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 eiv has to be provided in the payload.
Protect or unprotect a phone number. The received token is length-preserving. May return leading zeroes.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
eiv(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 eiv has to be provided in the payload.
Protect or unprotect a phone number. The received token is length-preserving. May return leading zeroes.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
eiv(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 eiv has to be provided in the payload.
Protect or unprotect a phone number. The received token is length-preserving. May return leading zeroes.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
year(optional) Set to true to leave the year in the clear. Must be set to true when unprotecting the string tokenized using this option. Accepts: [ true | false ]. Defaults to false.
Protect or unprotect a National Insurance Number (UK). The returned NIN is case-, length- and position-preserving, i.e., generated letters and numbers will adhere to their original position. Note that some NIN logic, i.e. restricted letters, is not preserved.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
Protect or unprotect a Social Security Number (US). The returned SSN is length- and format-preserving. Note that some SSN logic, i.e. restricted numbers within digit groups, is not preserved.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
eiv(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 eiv has to be provided in the payload.
Protect or unprotect a Credit Card Number. The returned CCN is not length-preserving. The endpoint accepts partial CCN protection, i.e. leaving the 8-digit BIN in the clear.
ATTRIBUTES:
data(required) Input data to transform.
user(optional) Choose a user to impersonate from the list of pre-configured roles.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
OPTIONS:
bin(optional) Set to true to leave the 8-digit BIN number in the clear. Must be set to true when unprotecting the string tokenized using this option. Accepts: [ true | false ]. Defaults to false.
eiv(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 eiv has to be provided in the payload.
Protect or unprotect a passport number. The returned passport number is case-, length- and position-preserving (i.e., generated letters and numbers will adhere to their original position). Note that some passport logic, i.e. restricted letters, is not preserved.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
Protect or unprotect an Internation Banking Account Number. The returned IBAN is case-, length- and position-preserving. Note that some IBAN logic, i.e., producing valid country codes or a checksum validation, is not supported. The endpoint accepts partial IBAN protection, i.e., leaving the letters in the clear.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
alpha(optional) Set to true to leave the original letters in the clear. Must be set to true when unprotecting the string tokenized using this option. Accepts: [ true | false ]. Defaults to false.
eiv(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 eiv has to be provided in the payload. Note that this option is only available if alpha is set to true.
Protect or unprotect a string. Maximum length of the string is 128 characters. The returned string is not length-preserving neither case-preserving.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
eiv(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 eiv has to be provided in the payload.
Protect or unprotect a number. The returned number is length-preserving. The endpoint might generate numbers with leading zeros.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
eiv(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 eiv has to be provided in the payload.
Protect or unprotect sample text using encryption. Received text must be hex encoded. The returned value is hex encoded. There is no limitation on the text’s length however payload limits apply.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
Protect or unprotect a datetime string The endpoint accepts partial timestamp protection, i.e., leaving the year value in the clear. Supported formats: YYYY/MM/DD and YYYY/MM/DD HH:MM:SS. Supported delimiters: /, -, .; space or T are supported between date and time.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Specify if to protect or unprotect data. Accepts: [ protect | unprotect ].
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
year(optional) Set to true to leave the year in the clear. Must be set to true when unprotecting the string tokenized using this option. Accepts: [ true | false ]. Defaults to false.
Automatic detection & protection of sensitive data
GenAI Security endpoints focus on automated sensitive data discovery and protection. You can detect sensitive data and choose to automatically protect the findings. Protegrity’s context-aware models are leveraged to identify sensitive data within provided input. Currently the classification can only be generated for texts in English.
This collection includes pre-release functionality and is subject to change in the future releases of the platform. We are actively iterating over this offering and welcome industry insight to help shape up the platform.
UPCOMING ENHANCEMENTS:
Improved PII detection in sentences without punctuation
Improved detection of emails and zipcodes provided without context
Improved detection of account numbers in large payloads
Detect and classify sensitive data in a given input. The endpoint will return a classification and confidence score for every sensitive attribute found, alongside its location – a column name or a start and end index. Confidence score returns values from 0.1 to 1. The higher the confidence score, the more the product is sure of the PII classification it produced. We recommend using the confidence score to prioritize inspection of found sensitive data.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Type of operation to perform. Choose classify to only detect and classify data. Option protect deidentifies data. Option unprotect restores de-identified data to its original values. Accepts: [ classify | protect | unprotect ]
OPTIONS:
format(required) Specify the format of the input data. Currently the API only supports the option text for unstructured text. Accepts: [ text ].
SAMPLE REQUEST
curl --location 'https://api.playground.protegrity.com/v1/ai'\
--header 'x-api-key: <API_Key>'\
--header 'Content-Type: application/json'\
--header 'Authorization: <JWT_TOKEN>'\
--data '{
"operation": "classify",
"options": {
"format": "text"
},
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}'
import requests
import json
JWT_Token ="<JWT_TOKEN>"API_Key ="<API_Key>"url ='https://api.playground.protegrity.com/v1/ai'headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token }
data = {
"options": {
"format": "text",
"raw": "false" },
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}
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;
publicclassAPIRequest { publicstaticvoidmain(String[] args) {
try {
String JWT_Token ="<JWT_TOKEN>" String API_Key ="<API_Key>" URI uri =new URI("https://api.playground.protegrity.com/v1/ai");
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 ="{ \"options\": {\n"+//" \"format\": \"text\",\n"+//" \"raw\": false\n"+//" },\n"+//" \"data\": [\"Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!\"]\n"+//" }";
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/ai',
{ method:'POST',
headers: { 'x-api-key':'<API_Key>', 'Content-Type':'application/json', 'Authorization':'<JWT_TOKEN>' },
body:JSON.stringify({
"options": {
"format":"text",
"raw":false },
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
packagemainimport (
"io""fmt""strings""net/http" )
funcmain() {
JWT_Token:="<JWT_TOKEN>"API_Key:="<API_Key>"url:="https://api.playground.protegrity.com/v1/ai"data:=strings.NewReader(`{
"options": {
"format": "text",
"raw": false
},
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}`)
req, err:=http.NewRequest("POST", url, data)
iferr!=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)
iferr!=nil {
fmt.Println(err)
return }
deferresp.Body.Close()
body, err:=io.ReadAll(resp.Body)
iferr!=nil {
fmt.Println(err)
return }
fmt.Println(string(body))
}
Detect, classify, and protect sensitive data in a given input. The endpoint will protect the attributes classified as sensitive with a confidence score of 0.68 or more.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Type of operation to perform. Choose classify to only detect and classify data. Option protect deidentifies data. Option unprotect restores de-identified data to its original values. Accepts: [ classify | protect | unprotect ]
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
format(required) Specify the format of the input data. Currently the API only supports the option text for unstructured text. Accepts: [ text ].
type(optional) Specify the protection mechanism. Option mask replaces all attributes with ‘*****’. Option tokenize applies a tokenization method that matches the classification of the found attribute. Accepts: [ mask | tokenize ]. Defaults to mask.
tags(optional) Specify if to include tags to mark protected attributes with their assigned classification label. Tags are required for reversing the protection. Accepts: [ true | false ]. Defaults to true.
threshold(optional) Set to the preferred confidence score threshold. Protection will be applied to attributes identified as matching or over the set threshold. Set a to numeric value. If not specified, the threshold is configured to 0.68.
eiv(optional) Provide your custom initialization vector to introduce additional variance in the output. The input 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 eiv has to be provided in the payload.
SAMPLE REQUEST
curl --location 'https://api.playground.protegrity.com/v1/ai'\
--header 'x-api-key: <API_Key>'\
--header 'Content-Type: application/json'\
--header 'Authorization: <JWT_TOKEN>'\
--data '{
"operation": "protect",
"options": {
"format": "text",
"type": "mask",
"tags": false,
"threshold": 0.7
},
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}'
import requests
import json
JWT_Token ="<JWT_TOKEN>"API_Key ="<API_Key>"url ='https://api.playground.protegrity.com/v1/ai'headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token }
data = {
"operation": "protect",
"options": {
"format": "text",
"type": "mask",
"tags": False,
"threshold": 0.7 },
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}
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;
publicclassAPIRequest { publicstaticvoidmain(String[] args) {
try {
String JWT_Token ="<JWT_TOKEN>";
String API_Key ="<API_Key>";
URI uri =new URI("https://api.playground.protegrity.com/v1/ai");
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 ="{ \"operation\": \"protect\",\n"+//" \"options\": {\n"+//" \"format\": \"text\",\n"+//" \"type\": \"mask\",\n"+//" \"tags\": \"false\",\n"+//" \"threshold\": \"0.7\",\n"+//" },\n"+//" \"data\": [\"Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!\"]\n"+//" }";
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/ai',
{ method:'POST',
headers: { 'x-api-key':'<API_Key>', 'Content-Type':'application/json', 'Authorization':'<JWT_TOKEN>' },
body:JSON.stringify({
"operation":"protect",
"options": {
"format":"text",
"type":"mask",
"tags":false,
"threshold":0.7 },
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
packagemainimport (
"io""fmt""strings""net/http" )
funcmain() {
JWT_Token:="<JWT_TOKEN>"API_Key:="<API_Key>"url:="https://api.playground.protegrity.com/v1/ai"data:=strings.NewReader(`{
"operation": "protect",
"options": {
"format": "text",
"type": "mask",
"tags": false,
"threshold": 0.7
},
"data": ["Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"]
}`)
req, err:=http.NewRequest("POST", url, data)
iferr!=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)
iferr!=nil {
fmt.Println(err)
return }
deferresp.Body.Close()
body, err:=io.ReadAll(resp.Body)
iferr!=nil {
fmt.Println(err)
return }
fmt.Println(string(body))
}
SAMPLE RESPONSE
{"results": "Hello, this is ############## from Air Industries. Could you give me a call back to my mobile number ############. Have a lovely day!"}
Unprotect sensitive data in a given input, i.e. revert previously tokenized values to their original contents. Provided text must include tags to enable this transformation.
ATTRIBUTES:
data(required) Input data to transform.
operation(required) Type of operation to perform. Choose classify to only detect and classify data. Option protect deidentifies data. Option unprotect restores de-identified data to its original values. Accepts: [ classify | protect | unprotect ]
user(optional) Choose a user to impersonate from the list of pre-configured roles.
OPTIONS:
format(required) Specify the format of the input data. Currently the API only supports the option text for unstructured text. Accepts: [ text ].
SAMPLE REQUEST
curl --location 'https://api.playground.protegrity.com/v1/ai'\
--header 'x-api-key: <API_Key>'\
--header 'Content-Type: application/json'\
--header 'Authorization: <JWT_TOKEN>'\
--data '{
"operation": "unprotect",
"format": "text",
"user": "paloma.torres",
"data": ["Hello, this is [PERSON]SQnnLOQMw TEwP[/PERSON] from Air Industries. Could you give me a call back to my mobile number [PHONE_NUMBER]025-016-8606[/PHONE_NUMBER]. Have a lovely day!"]
}'
import requests
import json
JWT_Token ="<JWT_TOKEN>"API_Key ="<API_Key>"url ='https://api.playground.protegrity.com/v1/ai'headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token }
data = {
"operation": "unprotect",
"format": "text",
"user": "paloma.torres",
"data": ["Hello, this is [PERSON]SQnnLOQMw TEwP[/PERSON] from Air Industries. Could you give me a call back to my mobile number [PHONE_NUMBER]025-016-8606[/PHONE_NUMBER]. Have a lovely day!"]
}
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;
publicclassAPIRequest { publicstaticvoidmain(String[] args) {
try {
String JWT_Token ="<JWT_TOKEN>";
String API_Key ="<API_Key>";
URI uri =new URI("https://api.playground.protegrity.com/v1/ai");
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 ="{ \"operation\": \"unprotect\",\n"+//" \"options\": {\n"+//" \"format\": \"text\",\n"+//" \"user\": \"paloma.torres\",\n"+//" },\n"+//" \"data\": [\"Hello, this is [PERSON]SQnnLOQMw TEwP[/PERSON] from Air Industries. Could you give me a call back to my mobile number [PHONE_NUMBER]025-016-8606[/PHONE_NUMBER]. Have a lovely day!\"]\n"+//" }";
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/ai',
{ method:'POST',
headers: { 'x-api-key':'<API_Key>', 'Content-Type':'application/json', 'Authorization':'<JWT_TOKEN>' },
body:JSON.stringify({
"operation":"unprotect",
"format":"text",
"user":"paloma.torres",
"data": ["Hello, this is [PERSON]SQnnLOQMw TEwP[/PERSON] from Air Industries. Could you give me a call back to my mobile number [PHONE_NUMBER]025-016-8606[/PHONE_NUMBER]. Have a lovely day!"]
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
packagemainimport (
"io""fmt""strings""net/http" )
funcmain() {
JWT_Token:="<JWT_TOKEN>"API_Key:="<API_Key>"url:="https://api.playground.protegrity.com/v1/ai"data:=strings.NewReader(`{
"operation": "unprotect",
"format": "text",
"user": "paloma.torres",
"data": ["Hello, this is [PERSON]SQnnLOQMw TEwP[/PERSON] from Air Industries. Could you give me a call back to my mobile number [PHONE_NUMBER]025-016-8606[/PHONE_NUMBER]. Have a lovely day!"]
}`)
req, err:=http.NewRequest("POST", url, data)
iferr!=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)
iferr!=nil {
fmt.Println(err)
return }
deferresp.Body.Close()
body, err:=io.ReadAll(resp.Body)
iferr!=nil {
fmt.Println(err)
return }
fmt.Println(string(body))
}
SAMPLE RESPONSE
{"results": "Hello, this is Peregrine Grey from Air Industries. Could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"}
7 - 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.
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.
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.
Detect and classify sensitive data in a given input. The endpoint will return a classification and confidence score for every sensitive attribute found, alongside its location – a column name or a start and end index. Confidence score returns values from 0.1 to 1. The higher the confidence score, the more the product is sure of the PII classification it produced. We recommend using the confidence score to prioritize inspection of found sensitive data.
The endpoint does not take any attributes and accepts plain text as payload.
HEADERS:
Content-Type(required) Format of data sent in the payload. Set to text/plain for processing unstructured text. Accepts: [ text/plain ].
SAMPLE REQUEST
curl --location 'https://api.playground.protegrity.com/v1/private/classify'\
--header 'x-api-key: <Group_API_Key>'\
--header 'Content-Type: application/json'\
--header 'Authorization: <JWT_TOKEN>'\
--data 'Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!'
import requests
import json
JWT_Token ="<JWT_TOKEN>"API_Key ="<Group_API_Key>"url ='https://api.playground.protegrity.com/v1/private/classify'headers = { 'x-api-key': API_Key, 'Content-Type': 'application/json', 'Authorization': JWT_Token }
data = {
"Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"}
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;
publicclassAPIRequest { publicstaticvoidmain(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/classify");
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 ="{ \"Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!\"}";
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/classify',
{ method:'POST',
headers: { 'x-api-key':'<Group_API_Key>', 'Content-Type':'application/json', 'Authorization':'<JWT_TOKEN>' },
body:"Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!" })
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
packagemainimport (
"io""fmt""strings""net/http" )
funcmain() {
JWT_Token:="<JWT_TOKEN>"API_Key:="<Group_API_Key>"url:="https://api.playground.protegrity.com/v1/private/classify"data:=strings.NewReader(`{
"Hello, this is Peregrine Grey from Air Industries, could you give me a call back to my mobile number 212-456-7890. Have a lovely day!"
}`)
req, err:=http.NewRequest("POST", url, data)
iferr!=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)
iferr!=nil {
fmt.Println(err)
return }
deferresp.Body.Close()
body, err:=io.ReadAll(resp.Body)
iferr!=nil {
fmt.Println(err)
return }
fmt.Println(string(body))
}
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.
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
✓
Ｘ
Ｘ
Ｘ
Ｘ
✓
Ｘ
Ｘ
*The data is returned as masked.
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
Ｘ
*
*The data is returned as masked.
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
7.6 - Anonymization SDK
Make your data unidentifiable
Anonymization is the underlying foundation of secure data sharing. Anonymization is a process of irreversible destruction of identifiable data through the removal of direct and indirect/quasi-identifiers in such a manner that the data subject is no longer identifiable. Process utilizes Data privacy models, risk models, and key metrics to redact and transform direct and quasi-identifiers to generalize a dataset.
This section showcases the Protegrity Anonymization SDK, its transformation methods, privacy models available, and the statistical features. Note that the Anonymization SDK has been adjusted for public use and as such it is not an exact representation of the GA product. The SDK is a Python library that can be imported to your Data Science environment, like Jupyter Notebook. The modified SDK requires a valid connection to the API Playground. For more information about requesting access to the Private Endpoints, please refer to our documentation.
[lib].Connection(url, api_key, jwt_token) Establish a connection to the Anonymization cluster. Set url to the Anonymization endpoint. Set the api_key to your group API Key, and the jwt_token to your token.
[lib].AnonElement(cluster, data, pty_storage=False) A dataframe object that represents the dataset to transform. In the job configuration, you will be calling transformations on each attribute fo the dataframe. Set cluster to the Anonymization cluster you authenticated to. Set the data to your dataframe, and keep the pty_storage as False.
[lib].K(num) assing to the dataframe to set the K value.
[lib].Redact() assign to an attribute to redact it.
[lib].Preserve() assign to an attribute to preserve it.
[lib].Gen_Interval([ level, [level] ], [ importance = num ]) specify the interval levels to generalize continuous data to – assign it to an attribute to transform. Specify its importance to instruct the algorithm to mantain the data granularity, if possible and set to high, or the opposite, if set to low.
[lib].Gen_Tree(pd.DataFrame(data=tree))) specify the hierarchy to generalize categorical data to – assign it to an attribute to transform. Specify its importance to instruct the algorithm to mantain the data granularity, if possible and set to high, or the opposite, if set to low.
[lib].MicroAgg(askdk.AggregateFunction.formula) specify a mathematical formula to group the data - assign it to an attribute to transform. Choose between mean and median for numeric data types (integer and decimal) or mode for all data types. Specify its importance to instruct the algorithm to mantain the data granularity, if possible and set to high, or the opposite, if set to low.
[lib].Gen_Mask(maskchar=mask) specify the mask to obfuscate data – assign it to an attribute to transform. Provide the masking character as mask. Specify its importance to instruct the algorithm to mantain the data granularity, if possible and set to high, or the opposite, if set to low.
[lib].Gen_Rounding([ level, [level] ], [ importance = num ]) specify the groups to round the data too. Both date-based and number-based rounding is supported. Specify its importance to instruct the algorithm to mantain the data granularity, if possible and set to high, or the opposite, if set to low.
[lib].LDiv(lfactor=num) configure the l value of the sensitive attribure as l to mantain the l-diversity within each equivalence class.
[obj].config.k k-value setting of the dataframe (needs to be updated with [lib].K(num)).
[obj].config[‘maxSuppression’] specify the maximum fraction of records allowed to be removed from the dataset to achieve the set privacy goals.
[obj].assign assign multiple settings to the dataframe.
[obj].describe list the characteristics and assigned transformations of each attribute in the dataframe.
[lib].anonymize(obj, pty_storage=False) run the anonymization job. Set the obj to your annotated dataframe, and keep the pty_storage as False. When assigned to an attribute it can be referenced later as a job object.
[job].status() monitor the status of the anonymization job.
[job].result() return the result of the anonymization job.
[job].riskStat() return the risk and utility statistics associated with the anonymization job.
Example
You can use the provided examples to get a feel of how Anonymization SDK works with data. The sample processes a dataset of synthetic banking customers, constructs an anonymization job, and measures the utility and re-identification risk of the produced dataset.