This is the multi-page printable view of this section. Click here to print.
The following sections describe key concepts for understanding the REST API.
Base URL:
https://{ProtectFuncName}.azurewebsites.net/api
Substitute the Protect function name recorded during the Protect function installation.
For Cloud API on Azure Government Cloud use the following URL:
https://{ProtectFuncName}.azurewebsites.us/api
Once the Cloud API on Azure is installed, you can export the OpenAPI documentation file from:
https://{ProtectFuncName}.azurewebsites.net/api/v1/openapi
Authentication and functions key are required to get the URL.
For Cloud API on Azure Government Cloud use the following URL:
https://{ProtectFuncName}.azurewebsites.us/api/v1/openapi
For testing the REST API, we recommend using a client tool, such as Postman.
The following encoding formats are supported in the REST API.
For every encoding, the resultant protected data is returned in the same encoding. For example, if request is hex-encoded, the response is also hex-encoded.
For more information about the encoding formats, refer to the Protection Methods Reference.
Encoding | Supported by data elements | Notes |
|---|---|---|
utf8 | All except binary data elements. | Default encoding if encoding is not specified. |
hex | All | Default encoding for binary data elements. |
base64 | All |
|
base64_mime | All |
|
base64_pem | All |
|
base64_url | All |
|
AWS Lambda service limits maximum size of payload to 6 MB. Client applications of Protegrity Cloud API must ensure their payload size is within this limit. This applies to all types of requests described below.
Performs a policy operation such as protect, unprotect, or reprotect.
URI
/v1/protect or /v1/unprotect or /v1/reprotect
Method
POST
Parameters
data: Input data to the policy operation.
data_element: Data element to use for the policy operation.
encoding: Optional, encoding of the data. One of: base64, base64_mime, base64_pem, base64_url, hex, or utf8. Defaults to hex for binary data elements, otherwise defaults to utf8.
external_iv: Optional, external initialization vector.
old_data_element: (reprotect) Data element for unprotecting the input.
old_external_iv: (reprotect) Optional, external initialization vector for the input.
query_id: Optional, identifier for the request.
user: User performing the operation.
Result
Returns the output of the policy operation.
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "Alphanum",
"data":[<data1>,<data2>]
}
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "Alphanum",
"external_iv": "abc123",
"data":[<data1>,<data2>]
}
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "deName",
"old_data_element": "Alphanum",
"data":[<data1>,<data2>]
}
Performs policy operations using different data elements for each data set.
URI
/v1/protect or /v1/unprotect or /v1/reprotect
Method
POST
Parameters
encoding: Optional, encoding of the data. One of: base64, base64_mime, base64_pem, base64_url, hex, or utf8. Defaults to hex for binary data elements, otherwise defaults to utf8.
query_id: Optional, prefix for the request identifier.
user: User performing the operation.
arguments[].data: Input data to the policy operation.
arguments[].data_element: Data element to use for the policy operation.
arguments[].external_iv: Optional, external initialization vector.
arguments[].id: Optional, request identifier.
arguments[].old_data_element: (reprotect) Data element for unprotecting the input.
arguments[].old_external_iv: (reprotect) Optional, external initialization vector for the input.
{
"encoding": "utf8",
"query_id": "query1234",
"user": <policy_user>,
"arguments": [
{
"id": "1",
"external_iv": "<external iv>",
"data_element": "<data element name>",
"data":["<data1>","<data2>"]
},
{
"data_element": <data element name>,
"data":["<data1>","<data2>"]
}
]
}
External IV
The External IV feature provides an additional level of security by allowing different tokenized results across protectors for the same input data and token element, depending on the External IV set on each protector. External IVs must adhere to certain guardrails and not all data elements support External IV. To read more about the Tokenization model with External IV, refer to the External Initialization Vector (IV) chapter in the Protection Methods Reference.
responsePayloadV1:
type: object
properties:
success:
type: bool
error_msg:
type: string
description: When success is false, error_msg is included
results:
type: array
items:
type: string
Example success:
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
If the request was successful, the success flag will always be true.
Example failure:
{
"error_msg": "token expired",
"success": false
}
If the request fails, the success flag will always be false.
Multi Data Elements Support Payload
responsePayloadV2:
type: object
properties:
success:
type: boolean
results:
type: array
items:
type: object
properties:
success:
type: bool
error_msg:
type: string
description: When success is false, error_msg is included
id:
type: string
description: When id is sent in the request payload, id is included in the response
results:
type: array
items:
type: string
Example success:
{
"encoding": "utf8",
"results":[
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
},
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
],
"success": true
}
If the all the subrequests were successful, the success flag will be true.
Example failure:
{
"results": [
{
"error_msg":
"Protect failed. Data element not found. Refer to audit log for details",
"success": false
},
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
],
"success": false
}
It is possible to have a mix of successful and unsuccessful results. In this case, the global success flag will be false.
Protegrity has multiple products with REST API capabilities, such as Protection Server (out of support), DSG, and the latest product - IAP REST. Each one has its use case. To help you move to cloud-native implementation, Cloud Product REST API supports legacy payload.
Performs a policy operation such as protect, unprotect, or reprotect.
Method
POST
Parameters
dataelementname: (protect/unprotect) Data element to use for the policy operation.
externaliv: (protect/unprotect) Optional, external initialization vector.
newdataelementname: (reprotect) Data element to use for the output.
newexternaliv: (reprotect) Optional, external initialization vector for the output.
olddataelementname: (reprotect) Data element to use for the input.
oldexternaliv: (reprotect) Optional, external initialization vector for the input.
policyusername: User performing the operation.
bulk.id: Optional, identifier for the request.
bulk.data[].content: Input data to the policy operation.
Result
Returns the output of the policy operation.
{
"protect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"protect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"externaliv": "abc123",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"unprotect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"reprotect": {
"policyusername": "user1",
"newdataelementname": "deName",
"olddataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
Example:
{"protect":{"bulk":{"returntype":"success","data":[{"returntype":"success","message":"Data
protection was successful.","content":"RGZBUFR4ODAzejFwNjQ5TWg0TEFpcFNqbA=="},{"returntype":"success",
"message":"Data protection was successful.","content":"aHNnVVB5QWFDYw=="}]}}}
By default, the Azure function app function support HTTPS.
To setup SSL Certificates in the Protect Function App please go to the following Azure documentation link: