v4 Specification

The Protegrity Data Protection API v4 is the recommended interface for all new integrations. AWS Lambda service limits the maximum size of a payload to 6 MB. Client applications must ensure their payload size is within this limit.

Overview

The Protegrity Data Protection API v4 (SecOps v4) lets callers protect, unprotect, and reprotect (unprotect with one data element, then protect with another) sensitive data values according to a configured data security policy.

This is the new, canonical JSON API and is the recommended interface for all new integrations. It replaces the older v1 and Legacy REST formats, which are now deprecated.

• Base path: /pty/api/secops/v4
• Content type: application/json for both request and response
• Method: all operations are HTTP POST

Endpoints

Authentication

Authentication uses a JWT bearer token supplied in the Authorization header (the scheme keyword is matched case-insensitively):

Authorization: Bearer <token>

Enforcement is configured at deployment time and controlled by two configuration properties: authorization (set to jwt to enable JWT mode) and jwt_verify (set to 1 to verify the token signature).

When authorization is set to jwt:

• A missing, empty, or malformed Authorization header returns HTTP 403, regardless of the jwt_verify setting.
• Signature and expiry verification runs only when jwt_verify is 1. A failed verification (bad signature, expired token, and so on) returns HTTP 403. When jwt_verify is not 1, the token is decoded for its claims but the signature is not checked.
• The user identity is taken from a JWT claim (configurable with jwt_user_claim, default cognito:username). See the user field note under Request for how the body user field interacts with this.

Request

protect / unprotect

{
  "user": "alice",
  "payload": [
    {
      "dataElement": "DE_SSN",
      "data": ["675-00-7848", "105-74-8112"],
      "encoding": "utf8",
      "externalIv": "s40de6wf6",
      "externaltweak": "e8wf6s30d",
      "id": "1"
    }
  ]
}

reprotect

The reprotect operation adds the new* fields that describe the target data element.

{
  "user": "alice",
  "payload": [
    {
      "dataElement": "DE_SSN",
      "newDataElement": "DE_SSN_2",
      "data": ["340-75-9971"],
      "externalIv": "s40de6wf6",
      "newExternalIv": "02983hd7sz",
      "externaltweak": "e8wf6s30d",
      "newExternaltweak": "h4egm1hjd"
    }
  ]
}

Field reference

Response

Success (HTTP 200)

Both full success and partial success return HTTP 200. The response envelope is { errorCount, results }, where the order of results matches the order of the input payload.

{
  "errorCount": 0,
  "results": [
    { "encoding": "utf8", "data": ["340-75-9971", "064-18-7624"], "returnCode": 8 }
  ]
}

Each result is one of two shapes:

• Success result (resultSuccess): returnCode (the engine’s success code — 6 for protect, 8 for unprotect, 50 for reprotect, or 11 when an inactive key was used), encoding, data[], and optional id.
• Failure result (resultFailure): returnCode (a non-success engine code), message, and optional id.

A partial-success response (one item failed, one succeeded) still returns HTTP 200:

{
  "errorCount": 1,
  "results": [
    { "id": "1", "message": "Input too short", "returnCode": 22 },
    { "id": "2", "encoding": "base64", "data": ["..."], "returnCode": 8 }
  ]
}

Error responses

Return codes

returnCode is the protection engine’s return code. A success result carries a success code; a failure result carries a failure code together with a descriptive message.

Success codes (on a success result):

Failure codes (on a failure result):

Examples

protect

Simple protect call with the minimum required input:

{
  "user": "alice",
  "payload": [
    { "data": ["George Washington"], "dataElement": "DE_NAME" }
  ]
}

Response:

{
  "errorCount": 0,
  "results": [
    { "encoding": "utf8", "data": ["EdVz2X i5a2FXNW5jR"], "returnCode": 6 }
  ]
}

Protect using FPE with an external tweak:

{
  "user": "alice",
  "payload": [
    {
      "data": ["675-00-7848", "105-74-8112"],
      "dataElement": "DE_FPE",
      "externaltweak": "e8wf6s30d"
    }
  ]
}

unprotect

Simple unprotect call with the minimum required input:

{
  "user": "alice",
  "payload": [
    { "data": ["EdVz2X i5a2FXNW5jR"], "dataElement": "DE_NAME" }
  ]
}

Response:

{
  "errorCount": 0,
  "results": [
    { "encoding": "utf8", "data": ["George Washington"], "returnCode": 8 }
  ]
}

reprotect

Simple reprotect call (from one data element to another):

{
  "user": "alice",
  "payload": [
    {
      "data": ["EdVz2X i5a2FXNW5jR"],
      "dataElement": "DE_NAME",
      "newDataElement": "DE_NAME_2"
    }
  ]
}

Response:

{
  "errorCount": 0,
  "results": [
    { "encoding": "utf8", "data": ["m9yGNp v2ZiB2YWx1"], "returnCode": 50 }
  ]
}

Error examples

A 400 response for a request-level validation error (for example, a missing payload):

{ "message": "'payload' parameter is missing" }

A 403 response when the authorization token is missing or expired:

{ "message": "Authorization header was not found" }

A 500 response for a configuration error:

{ "message": "JWT secret is missing" }

Headers

Migrating from v1 / Legacy