This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Version 4 (V4) Application Protector API on REST

Describes the Version 4 AP REST protector APIs that are available for protection and unprotection of data.

1 - List of REST APIs

Lists the AP REST APIs.

This section describes the AP REST APIs available for protection and unprotection of data.

1.1 - HTTP GET version

This API displays the version of the product being used.
URI
https://hostname/v4/version
Method
GET
Parameters
Hostname: Host name of the endpoint, as defined in the AP-REST deployment

Resource: The resource to be used, which is /v4/version

Result
This function returns the current version of the AP REST protector API.

Response

StatusResponse
200{"version":"10.0.0+25.4af059","components":{"jcoreVersion":"10.0.1+12.g0eb7","coreVersion":"2.1.1+20.g78ac6ac.2.1"}}

Example

$ curl 'https://<HostName>/v4/version' --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

1.2 - HTTP POST protect

This API returns protected data.
URI
https://hostname/v4/protect
Method
POST
Parameters
Hostname: Host name of the endpoint, as defined in the AP-REST deployment.

Resource: The resource to be used, which is /v4/protect.

Request Body

  • User: Name of the user executing the API. The user must be present in the policy.
  • Payload:
    • dataElement: Name of the data element used to protect the data. This field is mandatory.
    • data: Data to be protected. This field is mandatory.
    • externalIv: External Initialization Vector (IV) used for protecting the data.
    • externaltweak: External tweak used for protecting the data.
Result
This API returns protected data.

Example 1

Without external IV and external tweak

$ curl --location --request POST 'https://<hostname>/v4/protect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"TE_A_N_S13_L0R0_Y_ST","data":["bG9jaGFu"],"encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 1

Without external IV and external tweak

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "cEJPM2pF"
      ],
      "returnCode": 6
    }
  ]
}

Example 2

With external IV

$ curl --location --request POST 'https://<hostname>/v4/protect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"TE_A_N_S13_L0R0_Y_ST","data":["bG9jaGFu"],"externalIv":"cHJvdGVncml0eQ==","encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 2

With external IV

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "b2Rnb1ky"
      ],
      "returnCode": 6
    }
  ]
}

Example 3

With external tweak

$ curl --location --request POST 'https://<hostname>/v4/protect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"FPE_FF1_LA_APIP_L0R0_ASTNI_M2.UTF8","data":["bG9jaGFu"],"external_tweak_":"eIvJdGKncnl8eS==","encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 3

With external tweak

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "b2Rnb1ky"
      ],
      "returnCode": 6
    }
  ]
}

1.3 - HTTP POST unprotect

This API unprotects the protected data.
URI
https://hostname/v4/unprotect
Method
POST
Parameters
Hostname: Host name of the endpoint, as defined in the AP-REST deployment.

Resource: The resource to be used, which is /v4/unprotect.

Request Body

  • User: Name of the user executing the API.
  • Payload:
    • dataElement: Name of the data element used to unprotect the data. This field is mandatory.
    • data: Data to be unprotected. This field is mandatory.
    • externalIv: External Initialization Vector (IV) used for unprotecting the data.
    • externaltweak: External tweak used for unprotecting the data.
Result
This API returns unprotected data.

Example 1

Without external IV and external tweak

$ curl --location --request POST 'https://<hostname>/v4/unprotect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"TE_A_N_S13_L0R0_Y_ST","data":["cEJPM2pF"],"encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 1

Without external IV and external tweak

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "bG9jaGFu"
      ],
      "returnCode": 8
    }
  ]
}

Example 2

With external IV

$ curl --location --request POST 'https://<hostname>/v4/unprotect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"TE_A_N_S13_L0R0_Y_ST","data":["b2Rnb1ky"],"externalIv":"cHJvdGVncml0eQ==","encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 2

With external IV

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "bG9jaGFu"
      ],
      "returnCode": 8
    }
  ]
}

Example 3

With external tweak

$ curl --location --request POST 'https://<hostname>/v4/unprotect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"FPE_FF1_LA_APIP_L0R0_ASTNI_M2.UTF8","data":["b2Rnb1ky"],"external_tweak_":"eIvJdGKncnl8eS==","encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 3

With external tweak

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "bG9jaGFu"
      ],
      "returnCode": 8
    }
  ]
}

1.4 - HTTP POST reprotect

This API reprotects the data.
URI
https://hostname/v4/reprotect
Method
POST
Parameters
Hostname: Host name of the endpoint, as defined in the AP-REST deployment.

Resource: The resource to be used, which is /v4/reprotect.

Request Body

  • User: Name of the user executing the API.
  • Payload:
    • dataElement: Name of the data element used to initially protect the data. This field is mandatory.
    • newDataElement: Name of the data element used to reprotect the data. This field is mandatory.
    • data: Data to be protected. This field is mandatory.
    • externalIv: External Initialization Vector (IV) used for initially protecting the data.
    • newExternalIv: External IV used for reprotecting the data.
    • externaltweak: External tweak used for initially protecting the data.
    • newExternaltweak: External tweak used for reprotecting the data.
Result
This API reprotects the data.

Example 1

Without external IV and external tweak

$ curl --location --request POST 'https://<hostname>/v4/reprotect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"TE_A_N_S13_L0R0_Y_ST",newDataElement: TE_A_N_S13_L1R3_N,"data":["cEJPM2pF"],"encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 1

Without external IV and external tweak

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "bDlrdGhhbg=="
      ],
      "returnCode": 50
    }
  ]
}

Example 2

With external IV

$ curl --location --request POST 'https://<hostname>/v4/reprotect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"TE_A_N_S13_L0R0_Y_ST",newDataElement: TE_A_N_S13_L1R3_N,"data":["cEJPM2pF"],"externalIv":"cHJvdGVncml0eQ==","newExternalIv":"dJvKdGWndnM0eP==","encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 2

With external IV

The following response appears for the status code 200, if the API is invoked successfully.

   {
 "errorCount": 0,
 "results": [
   {
     "id": 1,
     "encoding": "base64",
     "data": [
       "c2Snd1mz"
     ],
     "returnCode": 50
   }
 ]
}

Example 3

With external tweak

$ curl --location --request POST 'https://<hostname>/v4/reprotect' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
--data '{"payload":[{"id":1,"dataElement":"FPE_FF1_LA_APIP_L0R0_ASTNI_M2.UTF8",newDataElement: FPE_FF1_LA_APIP_L1R1_ASTNI_M2.UTF8,"data":["cEJPM2pF"],"externaltweak":"eIvJdGKncnl8eS==","newExternaltweak_":"eKwLeHXoepN0fQ==","encoding":"base64"}],"user":"user1"}'
--cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response 3

With external tweak

The following response appears for the status code 200, if the API is invoked successfully.

    {
  "errorCount": 0,
  "results": [
    {
      "id": 1,
      "encoding": "base64",
      "data": [
        "d2Tmd1nz"
      ],
      "returnCode": 50
    }
  ]
}

1.5 - HTTP GET doc

This API returns the document specifications.
URI
https://hostname/v4/doc
Method
GET
Parameters
Hostname: Host name of the endpoint, as defined in the AP-REST deployment.

Resource: The resource to be used, which is /v4/doc.

Result
This API returns the document specification.

Example

$ curl --location --request GET 'https://<hostname>/v4/doc' \
--header 'Content-Type: application/json' \
--header 'X-Correlation-ID: k81d1fae-7dec-41g0-a765-90a0c31e6wf5' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

Response

The API returns the OpenAPI specifications YAML file.

1.6 - HTTP Headers

Overview about HTTP headers.

The client should send the required HTTP headers to the server to specify the type of data being sent in the payload. The content type also specifies the type of result being sent by the server to the client.

To send a JSON request and get a JSON response, specify the following HTTP header:

Content-Type: application/json

Only the Content-Type: application/json value is supported. It is mandatory to specify this value in the HTTP header.

To uniquely identify each HTTP request, specify the correlation ID in the HTTP header:

X-Correlation-ID: <Correlation ID>

Correlation ID is used in audit logs. This is an optional value.

2 - V4 AP REST HTTP Response Codes

Lists the response codes generated for the HTTP REST requests sent to the v4 AP REST APIs. It also specifies the corresponding audit code generated in the logs.
Error MessagesOperationAudit Code in LogsHTTP Response Code
Failed to decode Base64
  • Protect
  • Unprotect
  • Reprotect
No audit code generated400
The content of the input data is not valid
  • Protect
  • Unprotect
  • Reprotect
44400
Unsupported algorithm or unsupported action for the specific data element
  • Protect
  • Unprotect
  • Reprotect
26400
Data is too long to be protected/unprotected
  • Protect
  • Unprotect
  • Reprotect
23400
Data is too short to be protected/unprotected
  • Protect
  • Unprotect
  • Reprotect
22400
The user does not have the appropriate permissions to perform the requested operation
  • Protect
  • Unprotect
  • Reprotect
3400
The data element could not be found in the policy
  • Protect
  • Unprotect
  • Reprotect
1401
The username could not be found in the policy
  • Protect
  • Unprotect
  • Reprotect
2400
Data unprotect operation failed. with correlationId <CorrelationID>Unprotect9400
Tweak input is too long. with correlationId <Correlation ID>
  • Protect
  • Unprotect
  • Reprotect
15200
Failed to send logs, connection refused ! with correlationId <Correlation ID>
  • Protect
  • Unprotect
  • Reprotect
51400
Policy not available with correlationId <Correlation ID>
  • Protect
  • Unprotect
  • Reprotect
31400

The Correlation ID appears in the error message only if it has been specified in the HTTP header.