v1 Specification

Describes the v1 REST API specification

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.

Request

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.

Example 1 - without external IV

{
  "encoding": "utf8",
  "query_id": "1",
  "user": "user1",
  "data_element": "Alphanum",
  "data":[<data1>,<data2>]
}

Example 2 - with external IV

{
  "encoding": "utf8",
  "query_id": "1",
  "user": "user1",
  "data_element": "Alphanum",
  "external_iv": "abc123",
  "data":[<data1>,<data2>]
}

Example 3 - reprotect

{
  "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.

Note

When multiple data elements are sent in the payload, the Cloud API generates an audit log per argument. The Cloud API appends the argument id, if it exists, to the query_id. For example: query_id.id:{id}. If an argument id is not provided then the index in the argument array is appended to the query_id. For example: query_id.index:{index}.

Example 4 - multiple data elements support payload

{
  "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.

Response

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.

Feedback

Was this page helpful?

Last modified : January 08, 2026