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.