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

Return to the regular view of this page.

Protegrity REST APIs

Overview of the Policy Management and Encrypted Resilient Package REST APIs.

1: Accessing the Protegrity REST APIs
2: View the Protegrity REST API Specification Document
3: Using the Common REST API Endpoints
4: Using the Policy Management REST APIs
5: Using the Encrypted Resilient Package REST APIs

The Protegrity REST APIs include the following APIs:

Policy Management REST APIs The Policy Management REST APIs are used to create or manage policies. The policy management functions performed from the ESA Web UI can also be performed using the REST APIs.
Encrypted Resilient Package APIs The Encrypted Resilient Package REST APIs include the REST API that is used to encrypt and export a resilient package, which is used by the resilient protectors.
For more information on how the REST API is used to export the encrypted resilient package in an immutable policy deployment, refer to the section DevOps Approach for Application Protector.

1 - Accessing the Protegrity REST APIs

Overview of how to access the Protegrity REST APIs.

The following section lists the requirements for accessing the Protegrity REST APIs.

Available endpoints - Protegrity has enabled the following endpoints to access the REST APIs.
Base URL
https://{ESA IP address or Hostname}/pty/<Version>/<API>
Where:
- ESA IP address or Hostname: Specifies the IP address or Hostname of the ESA.
- Version: Specifies the version of the API.
- API: Endpoint of the REST API.
Authentication - You can access the REST APIs using basic authentication, client certificates, or tokens. The authentication depends on the type of REST API that you are using. For more information about accessing the REST APIs using these authentication mechanisms, refer to the section Accessing REST API Resources.
Authorization - You must assign the permissions to roles for accessing the REST APIs. For more information about the roles and permissions required, refer to the section Managing Roles.

2 - View the Protegrity REST API Specification Document

Access and view the REST API specification document. Use an OpenAPI specification editor, such as Swagger Editor, to generate samples.

The steps mentioned in this section contains the usage of Docker containers and services to download and launch the images for Swagger Editor within a Docker container.

For more information about Docker, refer to the Docker documentation.

The following example uses Swagger Editor to view the REST API specification document. In this example, JSON Web Token (JWT) is used to authenticate the REST API.

Install and start the Swagger Editor.
Download the Swagger Editor image within a Docker container using the following command.
```
docker pull swaggerapi/swagger-editor
```
Launch the Docker container using the following command.
```
docker run -d -p 8888:8080 swaggerapi/swagger-editor
```
Paste the following address on a browser window to access the Swagger Editor using the specified host port.
```
http://localhost:8888/
```
Download the REST API specification document using the following command.
```
curl -H "Authorization: Bearer ${TOKEN}" "https://<Appliance IP address or Hostname>/pty/<Version>/<API>/doc" -H "accept: application/x-yaml" --output <api-doc>.yaml 
```
In this command, TOKEN is the environment variable that contains the JWT token used to authenticate the REST API.
Drag and drop the downloaded <api-doc>.yaml file into a browser window of the Swagger Editor.

Generating the REST API Samples Using the Swagger Editor

Perform the following steps to generate samples using the Swagger Editor.

Open the <api-doc>.yaml file in the Swagger Editor.
On the Swagger Editor UI, click on the required API request.
Click Try it out.
Enter the parameters for the API request.
Click Execute.
The generated Curl command and the URL for the request appears in the Responses section.

3 - Using the Common REST API Endpoints

Explains the usage of the Common APIs with some generic samples.

The following section specifies the common operations that are applicable to all the Protegrity REST APIs.

The Base URL for each API will change depending on the version of the API being used. The following table specifies the version that you must use when executing the common operations for each API.

REST API	Version in the Base URL <Version>
Policy Management	v2
Encrypted Resilient Package	v1

Common REST API Endpoints

The following table lists the common operations for the Protegrity REST APIs.

REST API	Description
/version	Retrieves the service versions that are supported by the Protegrity REST APIs on the ESA.
/health	This API request retrieves the health information for the Protegrity REST APIs and identifies whether the corresponding service is running.
/doc	This API request retrieves the API specification document.
/log	This API request retrieves current log level set for the corresponding REST API logs.
/log	This API request changes the log level for the REST API service during run-time. The level set through this resource is persisted until the corresponding service is restarted. This log level overrides the log level defined in the configuration.

Retrieving the Supported Service Versions

This API retrieves the service versions that are supported by the corresponding REST API service on the ESA.

Base URL: https://{ESA IP address}/pty/<Version>/<API>
Path: /version
Method: GET

CURL request syntax

curl -H "Authorization: Bearer TOKEN" -X GET "https://{ESA IP address}/pty/<Version>/<API>/version"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/version"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).

Sample CURL request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/version"

This sample request uses the JWT token authentication.

Sample CURL response

{"version":"1.8.1","buildVersion":"1.8.1-alpha+605.gfe6b1d.master"}

Retrieving the Service Health Information

This API request retrieves the health information of the REST API service and identifies whether the service is running.

Base URL: https://{ESA IP address}/pty/<Version>/<API>
Path: /health
Method: GET

CURL request syntax

curl -H "Authorization: Bearer <TOKEN>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/health"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/health"

Authentication credentials

TOKEN - Enviroment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).

Sample CURL request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v2/pim/health"

This sample request uses the JWT token authentication.

Sample CURL response

{
  "isHealthy" : true
}

Where,

isHealthy: true - Indicates that the service is up and running.
isHealthy: false - Indicates that the service is down.

Retrieving the API Specification Document

This API request retrieves the API specification document.

Base URL: https://{ESA IP address}/pty/<Version>/<API>
Path: /doc
Method: GET

CURL request syntax

curl -H "Authorization: Bearer <Token>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/doc"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/doc"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).

Sample CURL requests

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/doc"

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/doc" -o "rps.yaml"

These sample requests uses the JWT token authentication.

Sample CURL responses

The Encrypted Resilient Package API specification document is displayed as a response. If you have specified the “-o” parameter in the CURL request, then the API specification is copied to a file specified in the command. You can use the Swagger UI to view the API specification document.

Retrieving the Log Level

This API request retrieves current log level set for the REST API service logs.

Base URL: https://{ESA IP address}/pty/<Version>/<API>
Path: /log
Method: GET

CURL request syntax

curl -H "Authorization: Bearer <TOKEN>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/log"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/log"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).

Sample CURL request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v2/pim/log"

This sample request uses the JWT token authentication.

Sample CURL response

{
  "level": "INFO"
}

Setting Log Level for the REST API Service Log

This API request changes the REST API service log level during run-time. The level set through this resource persists until the corresponding service is restarted. This log level overrides the log level defined in the configuration.

Base URL: https://{ESA IP address}/pty/<Version>/<API>
Path: /log
Method: POST

CURL request syntax

curl -X POST "https://{ESA IP Address}/pty/<Version>/<API>/log" -H "Authorization: Bearer <TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"log level\"}"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -X POST "https://{ESA IP Address}/pty/<Version>/<API>/log" -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"log level\"}"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).

Request body elements

log level

Set the log level. The log level can be set to SEVERE, WARNING, INFO, CONFIG, FINE, FINER, or FINEST.

Sample CURL request

curl -X POST "https://{ESA IP Address}/pty/v1/rps/log" -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"SEVERE\"}"

This sample request uses the JWT token authentication.

Sample response

The log level is set successfully.

4 - Using the Policy Management REST APIs

Explains the usage of the Policy Management APIs with some generic samples.

The user accessing these APIs must have the Security Officer permission for write access and the Security Viewer permission for read-only access.
For more information about the roles and permissions required, refer to the section Managing Roles.

The Policy Management API uses the v2 version.

If you want to perform common operations using the Policy Management REST API, then refer the section Using the Common REST API Endpoints.

The following table provides section references that explain usage of some of the Policy Management REST APIs. It includes an example workflow to work with the Policy Management functions. If you want to view all the Policy Management APIs, then use the /doc API to retrieve the API specification.

REST API	Section Reference
Policy Management initialization	Initializing the Policy Management
Creating an empty manual role that will accept all users	Creating a Manual Role
Create data elements	Create Data Elements
Create policy	Create Policy
Add roles and data elements to the policy	Adding roles and data elements to the policy
Create a default data store	Creating a default datastore
Deploy the data store	Deploying the Data Store
Get the deployment information	Getting the Deployment Information

Initializing the Policy Management

This section explains how you can initialize Policy Management to create the keys-related data and the policy repository. If you are initializing the Policy Management from the ESA Web UI, then the execution of this service is not required.

For more information about initializing the Policy Management from the ESA Web UI, refer to the section Initializing the Policy Management.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/init
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/init" -H "accept: application/json"

This sample request uses the JWT token authentication.

Creating a Manual Role

This section explains how you can create a manual role that accepts all the users.

For more information about working with roles, refer to the section Working with Roles.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/roles
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/roles" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"ROLE\",\"mode\":\"MANUAL\",\"allowAll\": true}

This sample request uses the JWT token authentication.

Creating Data Elements

This section explains how you can create data elements.

For more information about working with data elements, refer to the section Working with Data Elements.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/roles
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/dataelements" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\": \"DE_ALPHANUM\",\"description\": \"DE_ALPHANUM\",\"alphaNumericToken\":{\"tokenizer\":\"SLT_1_3\",\"fromLeft\": 0,\"fromRight\": 0,\"lengthPreserving\": true, \"allowShort\": \"YES\"}}"

This sample request uses the JWT token authentication.

Creating Policy

This section explains how you can create a policy.

For more information about working with policies, refer to the section Creating Policies.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/policies
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/policies" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"POLICY\",\"description\": \"POLICY\", \"template\":{\"access\":{\"protect\":true,\"reProtect\":true,\"unProtect\":true},\"audit\":{\"success\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false},\"failed\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false}}}}"

This sample request uses the JWT token authentication.

Adding Roles and Data Elements to a Policy

This section explains how you can add roles and data elements to a policy.

For more information about adding roles and data elements to a policy, refer to the sections Adding Data Elements to Policy and Adding Roles to Policy respectively.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/policies/1/rules
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/policies/1/rules" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"role\":\"1\",\"dataElement\":\"1\",\"noAccessOperation\":\"EXCEPTION\",\"permission\":{\"access\":{\"protect\":true,\"reProtect\":true,\"unProtect\":true},\"audit\":{\"success\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false},\"failed\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false}}}}"

This sample request uses the JWT token authentication.

Creating a Default Data Store

This section explains how you can create a default data store.

For more information about working with data stores, refer to the section Creating a Data Store.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/datastores
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/datastores" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"DS\",\"description\": \"DS\", \"default\":true}"

This sample request uses the JWT token authentication.

Deploying the Data Store

This section explains how you can deploy policies or trusted applications linked to a specific data store or multiple data stores.

For more information about deploying the Data Store, refer to the section Deploying Data Stores.

Deploying a Specific Data Store

This section explains how you can deploy policies and trusted applications linked to a specific data store. The specifications provided for the specific data store are applied and becomes the end-result.

Note: If you deploy an array with empty policies or trusted applications, or both, then the connected protectors contain empty definitions for these respective items.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/datastores/{dataStoreUid}/deploy
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/datastores/{dataStoreUid}/deploy" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"policies\":[\"1\"],\"applications\":[\"1\"]}"

This sample request uses the JWT token authentication.

Deploying Data Stores

This section explains how you can deploy data stores, which can contain the linking of either the policies or trusted applications, or both for the deployment.

Note: If you deploy a data store containing an array with empty policies or trusted applications, or both, then the connected protectors contain empty definitions for these respective items.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/deploy
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address}:443/pty/v2/pim/deploy" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"dataStores\":[{\"uid\":\"1\",\"policies\":[\"1\"],\"applications\":[\"1\"]},{\"uid\":\"2\",\"policies\":[\"2\"],\"applications\":[\"2\"]}]}"

This sample request uses the JWT token authentication.

Getting the Deployment Information

This section explains how you can check the complete deployment information. This service returns the list of the data stores with the connected policies and trusted applications.

Note: The result might contain data store information that is pending deployment after combining the Policy Management operations performed through the ESA Web UI and PIM API.

Base URL: https://{ESA IP address or Hostname}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Path: /pim/deploy
Method: GET

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address or Hostname}:443/pty/v2/pim/deploy" -H "accept: application/json"

This sample request uses the JWT token authentication.

5 - Using the Encrypted Resilient Package REST APIs

Explains the usage of the Encrypted Resilient Package APIs.

The Encrypted Resilient Package API is only used by the Immutable Resilient protectors.

Before you begin:

Ensure that the concept of resilient protectors and necessity of a resilient package is understood.
For more information on how the REST API is used to export the encrypted resilient package in an immutable policy deployment, refer to the section DevOps Approach for Application Protector.
Ensure that the RPS service is running on the ESA.
The user accessing this API must have the Export Resilient Package permission.
For more information about the roles and permissions required, refer to the section Managing Roles.

The Encrypted Resilient Package API uses the v1 version.

If you want to perform common operations using the Encrypted Resilient Package API, then refer the section Using the Common REST API Endpoints.

The following table provides a section reference to the Encrypted Resilient Package API.

REST API	Section Reference
Exporting the resilient package	Exporting Resilient Package

Exporting Resilient Package

This API request exports the resilient package that can be used with resilient protectors. You can use the Basic authentication, Certificate authentication, and JWT authentication for encrypting and exporting the resilient package.

Warning: Do not modify the package that has been exported using the RPS Service API. If you modify the exported package, then the package will get corrupted.

Important: The resilient package that has been exported using the Encrypted Resilient Package API is not FIPS-compliant.

Base URL

https://{ESA IP address or Hostname}/pty/v1/rps

Path

/export

Method

POST

CURL request syntax

Export API - KEK

curl -H "Authorization: Bearer <TOKEN>" -X POST https://{ESA IP address or Hostname}/pty/v1/rps/export\?version=1\&coreversion=1 -H "Content-Type: application/json" --data '{
    "kek":{
"publicKey":{
"label": "{Key_name}",
"algorithm": "{RSA_Algorithm}",
"value": "{Value of publickey}"
}
}' -o rps.json

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X POST https://{ESA IP address or Hostname}/pty/v1/rps/export\?version=1\&coreversion=1 -H "Content-Type: application/json" --data '{
    "kek":{
"publicKey":{
"label": "{Key_name}",
"algorithm": "{RSA_Algorithm}",
"value": "{Value of publickey}"
}
}' -o rps.json

Note: You can download the resilient package only from the IP address that is part of the allowed servers list connected to a Data Store. This is only applicable for the 10.0.x and 10.1.0 protectors.

Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Query parameters: version; Set the schema version of the exported resilient package that is supported by the specific protector.; coreversion; Set the Core policy schema version that is supported by the specific protector.
Request body elements: Encryption Method; The kek encryption can be used to protect the exported file.

Encryption Method	Sub-elements	Description
kek\publicKey	label	Name of the publicKey.
	algorithm	The RPS API supports the following algorithms: RSA-OAEP-SHA1 RSA-OAEP-256 RSA-OAEP-512 RSA1_5
	value	Specify the value of the publicKey.

Sample CURL request

Export API - KEK

curl -H "Authorization: Bearer ${TOKEN}" -X POST https://{ESA IP address or Hostname}/pty/v1/rps/export\?version=1\&coreversion=1 -H "Content-Type: application/json" --data '{
    "kek":{
"publicKey":{
"label": "key_name",
"algorithm": "RSA-OAEP-256",
"value": "-----BEGIN PUBLIC KEY-----MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1eq9vH5Dq8pwPqOSqB0YdY6ehBRNWCgYhh9z1X093id+42eTRDHMOpLXRLhOMdgOeeyEsue1s5ZEOKY9j2TcaVTRwLhSMfacjugfiknnUESziUi9mt+XFnSgk7n4t5EF7fjvriOQvHCp24xCbtwKQlOT3x4zUs/REyJ8FXSrFEvrzbb/mEFfYhp2J6c90CKYqbDX6SFW8WjphDb/kgqg/KfT8AlsllAnci4CZ+7u0Iw7GsRvEvrVUCbBsXfB7InTst3hTc4A7iiY36kSEn78mXtfLjWiMpzEBxOteohmXKgSAynI7nI8c0ZhHSoZLUSJ2IQUi25ho8uxd/v3fedTTD91zRTxMJKw8XDrwjXllH7FGgsWBUenkO2lRlfIYBDctjv1MB+QJlNo+gOTGg8sJ1czBm20VQHHcyHpCKNu2gKzqWqSU6iGcwGXPCKY8/yEpNyPVFS/i7GAp10jO+QdOBskPviiLFN5kMh05ZGBpyNvfAQantwGv15Ip0RJ3LTQbKE62DAGNcdP6rizwm9SSt0WcG58OenBX5eB0gWBRrZI5s3EkhThYXyxbvFWObMWb/3jMsE+O22NvqAxWSasPR1zS1WBf25ush3v6BGBO4Frl5kBRrTCSSfAZBDha5VqXOqR1XIdQKf8wKn5DSScpMRuyf3ymRGQf915CC7zwp0CAwEAAQ==-----END PUBLIC KEY-----"}
}
}' -o rps.json

This sample request uses the JWT token authentication.

Sample response

The rps.json file is exported.

Protect the encrypted resilient package with standard file permissions to ensure that only the dedicated protectors can access the package.