Using the Policy Management REST APIs

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

The Policy Management REST APIs will work only after you have installed the workbench.
For more information about installing the workbench, refer to the Installing Policy Workbench.

The user accessing these APIs must have the workbench_management_policy_write permission for write access and the workbench_management_policy_read permission for read-only access.
For more information about the roles and permissions required, refer to the section Workbench Roles and Permissions.

Note: The Policy Management API uses the v2 version.

To perform common operations, such as, retrieving the supported application versions, retrieving the API specification document, and so on using the Policy Management REST API, then refer to 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	Creating Data Elements
Create policy	Creating 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.

Base URL: https://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/init
Method: POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://<FQDN>: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 Roles.

Base URL: https://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/roles
Method: POST

Request Body

name: Name of the role. This is a mandatory field.
mode: Mode of the role. Specify MANUAL for a manually managed role.
allowAll: If true, the role accepts all users. The default value is false.

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://<FQDN>: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 Data Elements.

Base URL: https://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/dataelements
Method: POST

Request Body

name: Name of the data element. This is a mandatory field.
description: Description of the data element.
alphaNumericToken: Configuration object for alphanumeric tokenization.
- tokenizer: Tokenizer type to use. For example, SLT_1_3.
- fromLeft: Number of characters to preserve from the left.
- fromRight: Number of characters to preserve from the right.
- lengthPreserving: If true, the tokenized output preserves the original length.
- allowShort: Whether to allow tokenization of short values. Valid values: YES, NO.

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://<FQDN>: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.

Base URL: https://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/policies
Method: POST

Request Body

name: Name of the policy. This is a mandatory field.
description: Description of the policy.
template: Default permission template applied to roles added to the policy.
- access: Access permissions for the policy template.
  - protect: Allow protect operations.
  - reProtect: Allow re-protect operations.
  - unProtect: Allow unprotect operations.
- audit: Audit logging configuration for the policy template.
  - success: Audit settings for successful operations.
    - protect: Log successful protect operations.
    - reProtect: Log successful re-protect operations.
    - unProtect: Log successful unprotect operations.
  - failed: Audit settings for failed operations.
    - protect: Log failed protect operations.
    - reProtect: Log failed re-protect operations.
    - unProtect: Log failed unprotect operations.

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://<FQDN>: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://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/policies/1/rules
Method: POST

Request Body

role: ID of the role to add to the policy. This is a mandatory field.
dataElement: ID of the data element to add to the policy. This is a mandatory field.
noAccessOperation: Action to perform when access is denied. For example, EXCEPTION.
permission: Permission configuration for this role and data element combination.
- access: Access permissions.
  - protect: Allow protect operations.
  - reProtect: Allow re-protect operations.
  - unProtect: Allow unprotect operations.
- audit: Audit logging configuration.
  - success: Audit settings for successful operations.
    - protect: Log successful protect operations.
    - reProtect: Log successful re-protect operations.
    - unProtect: Log successful unprotect operations.
  - failed: Audit settings for failed operations.
    - protect: Log failed protect operations.
    - reProtect: Log failed re-protect operations.
    - unProtect: Log failed unprotect operations.

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://<FQDN>: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 Data Stores.

Base URL: https://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/datastores
Method: POST

Request Body

name: Name of the data store. This is a mandatory field.
description: Description of the data store.
default: If true, sets this data store as the default data store.

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://<FQDN>: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 become 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://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/datastores/{dataStoreUid}/deploy
Method: POST

Path Parameters

dataStoreUid: Unique identifier of the data store to deploy. This is a mandatory field.

Request Body

policies: Array of policy IDs to deploy to the data store.
applications: Array of trusted application IDs to deploy to the data store.

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://<FQDN>: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://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/deploy
Method: POST

Request Body

dataStores: Array of data store objects to deploy. Each object contains:
- uid: Unique identifier of the data store. This is a mandatory field.
- policies: Array of policy IDs to deploy to the data store.
- applications: Array of trusted application IDs to deploy to the data store.

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{FQDN}: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://{FQDN}/pty/v2
Authentication credentials: TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.
For more information about refreshing the JWT token, refer to the section Refresh token.
Path: /pim/deploy
Method: GET

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://<FQDN>:443/pty/v2/pim/deploy" -H "accept: application/json"

This sample request uses the JWT token authentication.

Sample Response

The API returns the list of data stores with their connected policies and trusted applications.

Feedback

Was this page helpful?

Last modified : July 29, 2026