Protegrity 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 Authentication and Token Management REST APIs
• 5: Using the Policy Management REST APIs
• 6: Using the Encrypted Resilient Package REST APIs
• 7: Roles and Permissions

1 - Accessing the Protegrity REST APIs

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

1. Available endpoints - Protegrity has enabled the following endpoints to access the REST APIs.

   Base URL

   https://<FQDN>/pty/<Version>/<API>

   Where:

   • FQDN: Fully Qualified Domain Name provided by the user during PPC installation.
   • Version: Specifies the version of the API.
   • API: Endpoint of the REST API.

2. Authentication - You can access the REST APIs using 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.

3. 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

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.

1. Install and start the Swagger Editor.

2. Download the Swagger Editor image within a Docker container using the following command.

   docker pull swaggerapi/swagger-editor
   

3. Launch the Docker container using the following command.

   docker run -d -p 8888:8080 swaggerapi/swagger-editor
   

4. Paste the following address on a browser window to access the Swagger Editor using the specified host port.

   http://localhost:8888/
   

5. Download the REST API specification document using the following command.

   curl "https://<FQDN>/pty/<Version>/<API>/doc" -H "accept: application/x-yaml" --output api-doc.yaml 
   

   In this command:

   • <Version> is the version number of the API. For example, v1 or v2.
   • <API> is the API for which you want to download the OpenAPI specifications document. For example, specify the value as pim to download the OpenAPI specifications for the Policy Management REST API. Similarly, specify the value as auth to download the OpenAPI specifications for the Authentication and Token Management API.
     For more information about the Policy Management REST APIs, refer to the section Using the Policy Management REST APIs.
     For more information about the Authentication and Token Management REST APIs, refer to the section Using the Authentication and Token Management REST APIs

6. 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.

1. Open the api-doc.yaml* file in the Swagger Editor.

2. On the Swagger Editor UI, click on the required API request.

3. Click Try it out.

4. Enter the parameters for the API request.

5. Click Execute.

   The generated Curl command and the URL for the request appears in the Responses section.

3 - Using the Common REST API Endpoints

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.

Common REST API Endpoints

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

Retrieving the Supported Application Versions

This API retrieves the application version information.

Base URL

https://{FQDN}/pty/<Version>/<API>

Path

/version

Method

GET

CURL request syntax

curl -X 'GET' \
  'https://<FQDN>/pty/v1/auth/version' \
  -H 'accept: application/json'

Authentication credentials

Not required.

Sample CURL request

curl -X 'GET' \
  'https://<FQDN>/pty/v1/auth/version' \
  -H 'accept: application/json'

Sample CURL response

{
  "version": "1.2.3",
  "buildVersion": "1.11.0-alpha+65.g9f0ae.master"
}

Retrieving the API Specification Document

This API request retrieves the API specification document.

Base URL

https://{FQDN}/pty/<Version>/<API>

Path

/doc

Method

GET

CURL request syntax

curl -X GET "https://<FQDN>/pty/<Version>/<API>/doc"

Authentication credentials

Not required.

Sample CURL requests

curl -X GET "https://<FQDN>/pty/v1/rps/doc"

curl -X GET "https://<FQDN>/pty/v1/rps/doc" -o "rps.yaml"

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 the current log level of the REST API service logs.

Base URL

https://{FQDN}/pty/<Version>/<API>

Path

/log

Method

GET

CURL request syntax

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/log" \
  -H "accept: application/json" \
  -H "Authorization: Bearer Token"

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 'GET' \
  "https://<FQDN>/pty/v1/auth/log" \
  -H "accept: application/json" \
  -H "Authorization: ${TOKEN}"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generate token.

Sample CURL request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/log" \
  -H "accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5"

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://{FQDN}/pty/<Version>/<API>

Path

/log

Method

POST

CURL request syntax

curl -X POST "https://<FQDN>/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://<FQDN>/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 Generate token.

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://<FQDN>/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.

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://{FQDN}/pty/<Version>/<API>

Path

/health

Method

GET

CURL request syntax

curl -H "Authorization: Bearer <TOKEN>" -X GET "https://<FQDN>/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://<FQDN>/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 Generate token.

Sample CURL request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://<FQDN>/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 Service Readiness Status

Base URL
https://{FQDN}/pty/<Version>/<API>

Path
/ready

Method
GET

CURL request syntax

curl -H "Authorization: Bearer <TOKEN>" -X GET "https://<FQDN>/pty/<Version>/<API>/ready

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://<FQDN>/pty/<Version>/<API>/ready

Authentication credentials

TOKEN - Environment variable containing the JWT token. For more information about creating a JWT token, refer to the section Generate token.

Sample CURL request

curl -X 'GET' \
  "https://amit.aws.protegrity.com/pty/v1/auth/ready" \
  -H "accept: */*" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the JWT token authentication.

Sample Server response

Code : 204

Response Header:

date: Wed,01 Apr 2026 
12:49:59 GMT  
server: uvicorn  x-correlation-id: a7c3d2b8-9cfb-4dd9-b31e-57f6225d3d33 

Retrieving the Service Liveness Status

Base URL
https://{FQDN}/pty/<Version>/<API>

Path
/live

Method
GET

CURL request syntax

curl -H "Authorization: Bearer <TOKEN>" -X GET "https://<FQDN>/pty/<Version>/<API>/live

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://<FQDN>/pty/<Version>/<API>/live

Authentication credentials

TOKEN - Environment variable containing the JWT token. For more information about creating a JWT token, refer to the section Generate token.

Sample CURL request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/live" \
  -H "accept: */*"
  -H "Authorization: Bearer <access_token>"

This sample request uses the JWT token authentication.

Sample Server response

Code : 204

Response Header:

date: Wed,01 Apr 2026 
12:49:59 GMT  
server: uvicorn  x-correlation-id: a7c3d2b8-9cfb-4dd9-b31e-57f6225d3d33 

4 - Using the Authentication and Token Management REST APIs

The Authentication and Token Management API uses the v1 version.

If you want to perform common operations using the Authentication and Token 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 Authentication and Token REST APIs. It includes sample examples to work with the Authentication and Token functions. If you want to view all the Authentication and Token APIs, then use the /doc API to retrieve the API specification.

Token Management

The following section lists the commonly used APIs to manage tokens.

Generate token

This API explains how you can generate an access token for authenticating the APIs.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/login/token

Method

POST

Request Body

• loginname: User name for authentication.
• password: Password for authentication.

Result

This API returns JWT access token in the response header and the refresh token in the response body. You can use the refresh token in the Refresh token API to obtain new access tokens without logging again.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/login/token" \
  -H "accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'loginname=<User name>&password=<Password>!'

Sample Response

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

Response body

{
  "status": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsIn",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e",
    "expiresIn": 300,
    "refreshExpiresIn": 900
  },
  "messages": []
}

Response header

content-length: 832 
 content-type: application/json 
 date: Thu,16 Oct 2025 10:30:53 GMT 
 pty_access_jwt_token: eyJhbGciOiJSUzI1NiIsInR4YRUw 
 strict-transport-security: max-age=31536000; includeSubDomains 

Refresh token

This API explains how to refresh an access token using the refresh token.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/login/refresh

Method

POST

Request Body

• refreshToken: Refresh token for getting a new access token.

Result

This API returns a new JWT access token in the response header and a new refresh token in the response body. You can use this refresh token to obtain new access tokens without logging again.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/login/token/refresh" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCINGFeZEf8hw"
}
'

Sample Response

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

Response body

{
  "status": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiI",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs",
    "expiresIn": 300,
    "refreshExpiresIn": 900
  },
  "messages": []
}

Response header

content-length: 832 
 content-type: application/json 
 date: Thu,16 Oct 2025 10:36:28 GMT 
 pty_access_jwt_token: eyJhbGciOiJSUzI1Nim95VHqh00vHfr8ip9RhyO-4FcxQ 
 strict-transport-security: max-age=31536000; includeSubDomains

Invalidate a user session

This API explains how you can invalidate a user session using the provided refresh token.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/logout

Method

POST

Request Body

• refreshToken: Refresh token for invalidating the user session.

Result

This API invalidates the user session using the refresh token in the Refresh token API.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/logout" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUOTEifQ."
}'

Sample Response

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

Response body

{
  "status": 0,
  "data": {
    "message": "Token invalidated successfully."
  },
  "messages": []
}

Update access token lifespan and SSO idle timeout

This API explains how you can update the access token lifespan and SSO idle timeout.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/token/lifespan/update

Method

POST

Request Body

• accessTokenLifespan: Updated lifespan of the access token in seconds.

Result

This API updates the lifespan of the access token. It also automatically updates the lifespan of the refresh token or the SSO idle timeout by adding 10 minutes to the lifespan of the access token.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/token/lifespan/update" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "accessTokenLifespan": 600
}'

Sample Response

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

Response body

"Token lifespan updated successfully."

Roles and Permissions Management

The following section lists the commonly used APIs for managing user roles and permissions.

List all permissions

This API returns a list of all the permissions available/defined in PPC.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/permissions

Method

GET

Request Body

No parameters.

Result

This API returns a list of all the permissions/roles available/defined in PPC.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/permissions" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

[
  {
    "name": "user_manager_admin",
    "description": "Permission to manage users with read-write access"
  },
  {
    "name": "saml_viewer",
    "description": "Permission to view SAML configurations with read-only access"
  },
  {
    "name": "user_manager_viewer",
    "description": "Permission to view users with read-only access"
  },
  {
    "name": "cli_access",
    "description": "Grants or restricts a user’s ability to access the CLI"
  },
  {
    "name": "saml_admin",
    "description": "Permission to update SAML configurations with read-write access"
  },
  {
    "name": "group_viewer",
    "description": "Permission to view groups with read-only access"
  },
  {
    "name": "group_admin",
    "description": "Permission to manage groups with read-write access"
  },
  {
    "name": "password_policy_admin",
    "description": "Permission to update password policy with read-write access"
  },
  {
    "name": "insight_viewer",
    "description": "Permission to view Insight Dashboard with read-only access."
  },
  {
    "name": "password_policy_viewer",
    "description": "Permission to view password policy with read-only access"
  },
  {
    "name": "role_viewer",
    "description": "Permission to view roles with read-only access"
  },
  {
    "name": "can_create_token",
    "description": "Permission to create/refresh tokens"
  },
  {
    "name": "insight_admin",
    "description": "Permission to view and edit Insight Dashboard with admin access."
  },
  {
    "name": "role_admin",
    "description": "Permission to manage roles with read-write access"
  },
  {
    "name": "web_admin",
    "description": "Permission to perform all operations available as part of the Web UI."
  }
]
 

List all roles

This API returns a list of all the roles available/defined in PPC.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/roles

Method

GET

Request Body

No parameters.

Result

This API returns a list of all the roles available for the logged-in user.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

[
  {
    "name": "directory_administrator",
    "description": "Directory Administrator",
    "composite": true,
    "permissions": [
      "saml_admin", "role_admin", "user_manager_admin", "can_create_token", "password_policy_admin", "group_admin"
    ]
  },
  {
    "name": "directory_viewer",
    "description": "Directory Viewer",
    "composite": true,
    "permissions": [
      "saml_viewer", "password_policy_viewer", "user_manager_viewer", "role_viewer", "group_viewer"
    ]
  },
  {
    "name": "security_administrator",
    "description": "Security Administrator",
    "composite": true,
    "permissions": [
      "can_fetch_package", "role_admin", "web_admin", "cli_access", "saml_admin", "can_export_certificates", "user_manager_admin", "can_create_token", "password_policy_admin", "group_admin", "insight_admin"
    ]
  },
  {
    "name": "security_viewer",
    "description": "Security Administrator Viewer",
    "composite": true,
    "permissions": [
      "saml_viewer", "password_policy_viewer", "insight_viewer", "user_manager_viewer", "role_viewer", "group_viewer"
    ]
  }  
]

Update role

This API enables you to update an existing role and its permissions.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/roles

Method

PUT

Request Body

• name: Role name.
• description: Description of the role.
• permissions: List of permissions that need to be updated for the existing role.

Result

This API updates the existing role and its permissions.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "admin",
  "description": "Administrator role",
  "permissions": [
    "perm1",
    "perm2"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "role_name": "admin",
  "status": "updated"
}

Create role

This API enables you to create a role.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/roles

Method

POST

Request Body

• name: Role name.
• description: Description of the role.
• permissions: List of permissions that need to created for the existing role.

Result

This API creates a roles with the requested permissions.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "admin",
  "description": "Administrator role",
  "permissions": [
    "perm1",
    "perm2"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "role_name": "admin",
  "status": "created"
}

Delete role

This API enables you to delete a role.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/roles

Method

DELETE

Request Body

• name: Role name.

Result

This API deletes the specific role.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "admin"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "role_name": "admin",
  "status": "deleted"
}

User Management

The following section lists the commonly used APIs for managing users.

Create user endpoint

This API enables you to create a user.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users

Method

POST

Request Body

• username: Name of the user. This is a mandatory field
• email: Email of the user.
• firstName: First name of the user.
• lastName: Last name of the user.
• enabled: Enable the user.
• password: Password for the user.
• roles: Roles to be assigned to the user.
• groups: Groups in which the user is included.
• identityProviders: An optional array that lists the SAML provider aliases to link the user, for example, AWS-IDP or AZURE-IDP, configured as part of the SAML SSO configuration.

Result

This API creates a user with a unique user ID.

Sample Request

{
  "username": "alpha",
  "email": "alpha@example.com",
  "firstName": "Alpha",
  "lastName": "User",
  "password": "StrongPassword123!",
  "roles": [
    "directory_admin"
  ],
  "groups": [
    "framework"
  ],
  "identityProviders": {
    "AWS-IDP": {
      "userId": "alpha@example.com",
      "userName": "alpha@example.com"
    }
  }
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "user_id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "username": "alpha"
}

Fetch users

This API enables you to retrieve the user details.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users

Method

GET

Request Body

No parameters.

Query Parameters

• max: Maximum number of entries that can retrieved.
• first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API retrieves a list of users.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/users?max=100&first=0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

[
  {
    "username": "admin",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User",
    "enabled": true,
    "id": "71c573a0-7412-475d-be67-4bf6fdf71404",
    "createdTimestamp": null,
    "attributes": null,
    "emailVerified": true
  },
  {
    "username": "alpha",
    "email": "alpha@example.com",
    "firstName": "Alpha",
    "lastName": "User",
    "enabled": true,
    "id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
    "createdTimestamp": 1760643896108,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "dfuser",
    "email": null,
    "firstName": "se",
    "lastName": "se",
    "enabled": false,
    "id": "12770ab4-d3a0-4243-8018-5bb1fb0d06d7",
    "createdTimestamp": 1760425034931,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "fds",
    "email": null,
    "firstName": "dsf",
    "lastName": "fs",
    "enabled": false,
    "id": "a1251ca4-664d-469a-b1c1-539fe8c73a9d",
    "createdTimestamp": 1760425052196,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "shiva",
    "email": "shiva.v@protegrity.com",
    "firstName": "shiva",
    "lastName": "v",
    "enabled": true,
    "id": "0743b449-c050-4e49-ba95-974cd2069a84",
    "createdTimestamp": 1760433609089,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "testuser1",
    "email": null,
    "firstName": "t",
    "lastName": "tes",
    "enabled": true,
    "id": "948c1484-45d7-4df9-aea4-9534ca2d1923",
    "createdTimestamp": 1760424968139,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "testuser2",
    "email": null,
    "firstName": "sdf",
    "lastName": "df",
    "enabled": true,
    "id": "d4961126-d324-4166-97e6-2fac1f40566a",
    "createdTimestamp": 1760425012482,
    "attributes": null,
    "emailVerified": false
  }
]

Update user endpoint

This API enables you to update the details of an user.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users

Method

PUT

Request Body

• id: ID of the user. This is a mandatory field
• email: Email of the user.
• firstName: First name of the user.
• lastName: Last name of the user.
• enabled: Enable the user.
• password: Password for the user.
• roles: Roles to be assigned to the user.
• groups: Groups in which the user is included.
• identityProviders: An optional array that lists the SAML provider aliases to link the user, for example, AWS-IDP or AZURE-IDP, configured as part of the SAML SSO configuration.

Result

This API updates the user details.

Sample Request

{
  "username": "alpha",
  "email": "alpha@example.com",
  "firstName": "Alpha",
  "lastName": "User",
  "password": "StrongPassword123!",
  "roles": [
    "directory_admin"
  ],
  "groups": [
    "framework"
  ],
  "identityProviders": {
    "AWS-IDP": {
      "userId": "alpha@example.com",
      "userName": "alpha@example.com"
    }
  }
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "updated",
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0"
}

Fetch User by Id

This API enables you to fetch the details of a specific user by specifying the user ID.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users/{user_id}

Method

GET

Request Body

No parameters.

Path Parameters

• user_id: Unique ID of the user. This is a mandatory field.

Result

This API retrieves the details of the specific user.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/users/7636708c-c714-4e8e-a3e6-f5fc6c49f9c0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "username": "alpha",
  "firstName": "lpha",
  "lastName": "User",
  "email": "alpha@example.com",
  "emailVerified": false,
  "enabled": true,
  "createdTimestamp": 1760643896108,
  "groups": [],
  "roles": [
    "directory_admin"
  ]
}

Delete user endpoint

This API enables you to delete a user.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users/{user_id}

Method

DELETE

Request Body

No parameters.

Path Parameters

• user_id: Unique ID of the user. This is a mandatory field.

Result

This API deletes the specified user.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/users/7636708c-c714-4e8e-a3e6-f5fc6c49f9c0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "deleted",
  "user_id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0"
}

Update user password endpoint

This API enables you to update the password of an existing user.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users/{user_id}/password

Method

PUT

Request Body

{
  "newPassword": "NewStrongPassword123!",
  "oldPassword": "OldPassword123!"
}

Path Parameters

• user_id: Unique ID of the user. This is a mandatory field.

Result

This API creates a roles with the requested permissions.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/users/password" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "newPassword": "NewStrongPassword123!",
  "temporary": false
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "password_updated",
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "temporary": false
}

Lock user account

This API enables you to lock the user account.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users/{user_id}/lock

Method

PUT

Request Body

No parameters.

Path Parameters

• user_id: Unique ID of the user. This is a mandatory field.

Result

This API locks the user.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/users/94070ecb-8639-41f4-b3e1-fda5cc7f8888/lock" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "locked",
  "user_id": "260e89e5-f77a-4aad-b733-22ca5c7c34a8"
}

unlock user account

This API enables you to unlock an existing user.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/users/password

Method

PUT

Request Body

• password: Password for the user.

Path Parameters

• user_id: Unique ID of the user. This is a mandatory field.

Result

This API unlocks the user.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/users/94070ecb-8639-41f4-b3e1-fda5cc7f8888/unlock" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "StrongPasword123!"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "unlocked",
  "user_id": "260e89e5-f77a-4aad-b733-22ca5c7c34a8",
  "password_temporary": true
}

Group Management

The following section lists the commonly used APIs for managing groups.

Fetch groups

This API enables you retrieve a list of all the groups.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/groups

Method

GET

Request Body

No parameters.

Query Parameters

• max: Maximum number of entries that can be retrieved.
• first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API a list of the available groups.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/groups?max=100&first=0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

[
  {
    "id": "d93f9953-b016-4db3-b786-4d4402997ac1",
    "name": "<group_name>",
    "description": "<group_description>",
    "attributes": {
      "groupType": [
        "local"
      ]
    },
    "members": [
      "member1",
      "member2"
    ],
    "roles": [
      "security_administrator"
    ]
  }
]

Create group endpoint

This API enables you create a group.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/groups

Method

POST

Request Body

• name: Name of the group. This is a mandatory field.
• description: Description of the group.
• members: List of user names that need to be added as members.
• roles: List of role names that need to be assigned to the group.

Result

This API creates a group with the specified members and roles.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/groups" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "developers",
  "description": "",
  "members": [
    "testuser1",
    "testuser2"
  ],
  "roles": [
    "service_admin",
    "user_manager"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{ “group_id”: “aee4c370-4e97-4b55-a072-0840fe83a2aa”, “name”: “developers”, “status”: “created”, “members_added”: 2, “roles_assigned”: 2 }

Update group endpoint

This API enables you update an existing group.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/groups

Method

PUT

Request Body

• group_id: Unique ID of the group. This is a mandatory field.
• members: Members added to the group.
• roles: Roles assigned to the group.

Result

This API updates the existing role and its permissions.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/groups" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "group_id": "group-uuid",
  "members": [
    "testuser2"
  ],
  "roles": [
    "service_admin"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "updated",
  "group_id": "d93f9953-b016-4db3-b786-4d4402997ac1",
  "members_updated": 1,
  "roles_updated": 1,
  "identity_providers_updated": null
}

Get group endpoint

This API enables you to get specific information by group ID.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/groups/{group_id}

Method

GET

Request Body

No parameters.

Path Parameters

• group_id: ID of the group that needs to be retrieved. This is a mandatory field.

Result

This API retrieves the details of the specified group.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/groups/aee4c370-4e97-4b55-a072-0840fe83a2aa" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "id": "aee4c370-4e97-4b55-a072-0840fe83a2aa",
  "name": "developers",
  "description": "",
  "attributes": {
    "groupType": [
      "local"
    ]
  },
  "members": [
    "john.doe",
    "jane.smith"
  ],
  "roles": [
    "service_admin",
    "directory_admin"
  ]
}

Delete groupend point

This API enables you to delete an existing group.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/groups/{group_id}

Method

DELETE

Request Body

No parameters.

Path Parameters

• group_id: ID of the group that needs to be deleted. This is a mandatory field.

Result

This API deletes the specified group.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/groups/aee4c370-4e97-4b55-a072-0840fe83a2aa" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"
  -d '{
  "deleteMembers":false
  }'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "deleted",
  "group_id": "aee4c370-4e97-4b55-a072-0840fe83a2aa"
}

SAML SSO Configuration

The following section lists the commonly used APIs for managing SAML providers.

List SAML providers

This API enables you to list the existing SAML providers.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/saml/providers

Method

GET

Request Body

No parameters

Result

This API retrieves a list of the existing SAML providers.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/saml/providers" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

[
{
  "alias": "azuread",
  "displayName": "Protegrity SAML SSO  (Azure AD IDP)",
  "providerId": "saml",
  "enabled": false,
  "config": {
    "postBindingLogout": "false",
    "singleLogoutServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "postBindingResponse": "true",
    "backchannelSupported": "false",
    "caseSensitiveOriginalUsername": "false",
    "encryptionAlgorithm": "RSA-OAEP",
    "xmlSigKeyInfoKeyNameTransformer": "KEY_ID",
    "idpEntityId": "https://sts.windows.net/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/",
    "useMetadataDescriptorUrl": "false",
    "loginHint": "false",
    "allowCreate": "true",
    "enabledFromMetadata": "true",
    "syncMode": "LEGACY",
    "authnContextComparisonType": "exact",
    "singleSignOnServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "wantAuthnRequestsSigned": "true",
    "allowedClockSkew": "0",
    "artifactBindingResponse": "false",
    "validateSignature": "true",
    "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "entityId": "https://<FQDN>/mysamlapp/saml/metadata",
    "signSpMetadata": "true",
    "wantAssertionsEncrypted": "false",
    "signatureAlgorithm": "RSA_SHA256",
    "sendClientIdOnLogout": "false",
    "wantAssertionsSigned": "false",
    "metadataDescriptorUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/federationmetadata/2007-06/federationmetadata.xml?appid=967110c7-a06b-432e-ad40-47859837a76c",
    "sendIdTokenOnLogout": "true",
    "postBindingAuthnRequest": "true",
    "forceAuthn": "false",
    "attributeConsumingServiceIndex": "0",
    "addExtensionsElementWithKeyInfo": "false",
    "principalType": "SUBJECT"
  }
},
{
  "alias": "azured",
  "displayName": "Protegrity 2 SAML SSO  (Azure AD IDP)",
  "providerId": "saml",
  "enabled": true,
  "config": {
    "postBindingLogout": "false",
    "singleLogoutServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "postBindingResponse": "true",
    "backchannelSupported": "false",
    "caseSensitiveOriginalUsername": "false",
    "xmlSigKeyInfoKeyNameTransformer": "KEY_ID",
    "idpEntityId": "https://sts.windows.net/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/",
    "useMetadataDescriptorUrl": "false",
    "loginHint": "false",
    "allowCreate": "true",
    "enabledFromMetadata": "true",
    "syncMode": "LEGACY",
    "authnContextComparisonType": "exact",
    "singleSignOnServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "wantAuthnRequestsSigned": "true",
    "allowedClockSkew": "0",
    "guiOrder": "0",
    "artifactBindingResponse": "false",
    "validateSignature": "true",
    "signingCertificate": "MIIC8DCCAdigAwIBAgIQf++2tyNO+YtIpa4MDh1hiQcoVX",
    "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "entityId": "https://<FQDN>/mysamlapp/saml/metadata",
    "signSpMetadata": "true",
    "wantAssertionsEncrypted": "false",
    "signatureAlgorithm": "RSA_SHA256",
    "sendClientIdOnLogout": "false",
    "wantAssertionsSigned": "false",
    "metadataDescriptorUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/federationmetadata/2007-06/federationmetadata.xml?appid=967110c7-a06b-432e-ad40-47859837a76c",
    "sendIdTokenOnLogout": "true",
    "postBindingAuthnRequest": "true",
    "forceAuthn": "false",
    "attributeConsumingServiceIndex": "0",
    "addExtensionsElementWithKeyInfo": "false",
    "principalType": "SUBJECT"
  }
}
]

Create SAML provider endpoint

This API enables you to create a SAML provider configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/saml/providers

Method

POST

Request Body

• alias: Unique alias for the SAML provider. This is a mandatory field.
• displayName: Display name for the SAML provider that will appear on the login page. This is a mandatory field.
• configType: Configuration type, either metadata URL or metadata file content. This is a mandatory field.
• metadataUrl: URL to fetch the SAML metadata from the identity provider. For example, https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml.
• metadataFileContent: SAML metadata XML content as a string. For example, <?xml version=\"1.0\"?>...</EntityDescriptor>.
• signingCertificate: X.509 certificate for signing SAML requests. Use the PEM format without the headers.
• nameIdPolicyFormat: NameID policy format for SAML authentication. For example, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
• forceAuthn: Force re-authentication of the user even if the user is already authenticated.
• validateSignature: Validate the SAML response and assertion signatures.
• wantAssertionsSigned: Require the SAML assertions to be signed.
• wantAssertionsEncrypted: Require the SAML assertions to be encrypted.
• signatureAlgorithm: Signature algorithm for SAML requests. For example, RSA_SHA256.
• attributeMapping: Mapping of SAML attributes to user attributes.
• enabled: Enable or disable the SAML provider.

For details of the each parameter, refer the documentation for the corresponding SAML provider.

Result

This API enables you to add a SAML provider.

Sample Request

{
  "alias": "azure-ad-saml",
  "configType": "metadataUrl",
  "displayName": "Azure AD SAML",
  "enabled": true,
  "forceAuthn": false,
  "metadataUrl": "https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml",
  "serviceProviderEntityId": "my-service-provider"
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{ “status”: “created”, “alias”: “test-azure-ad-saml”, “configType”: “metadataUrl”, “message”: “SAML provider created successfully from metadata” }

Note: The metadataFileContent parameter is not supported. You cannot upload or copy the metadata file. Instead, use the metadataUrl option to configure SAML.

Get SAML provider

This API enables you retrieve the details of a specific SAML provider.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/providers/{alias}

Method

GET

Request Body

No parameters.

Path Parameters

• alias: Alias of the SAML provider. This is a mandatory field.

Result

This API retrieves the details about the specific SAML provider.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/saml/providers/azure-ad-saml" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "alias": "azure-ad-saml",
  "displayName": "Azure AD SAML",
  "providerId": "saml",
  "enabled": true,
  "config": {
    "additionalProp1": {}
  }
}

Update SAML provider endpoint

This API enables you update the configurations of an existing SAML provider.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/providers/{alias}

Method

PUT

Request Body

No parameters.

Path Parameters

• alias: Alias of the SAML provider that you want to update. This is a mandatory field.

Result

This API updates the existing SAML provider.

Sample Request

{
  "alias": "azure-ad-saml",
  "configType": "metadataUrl",
  "displayName": "Azure AD SAML",
  "enabled": true,
  "forceAuthn": false,
  "metadataUrl": "https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml",
  "serviceProviderEntityId": "my-service-provider"
}

Note: The metadataFileContent parameter is not supported. You cannot upload or copy the metadata file. Instead, use the metadataUrl option to configure SAML.

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{ “status”: “updated”, “alias”: “azure-ad-saml” }

Delete SAML provider endpoint

This API enables you to delete the configuration of an existing SAML provider.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/saml/providers/{alias}

Method

DELETE

Request Body

No parameters.

Path Parameters

• alias: Alias of the SAML provider that you want to delete. This is a mandatory field.

Result

This API deletes the SAML provider.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/saml/providers/azure-ad-saml" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "deleted",
  "alias": "azure-ad-saml"
}

List SAML attribute mappers

This API enables you to list all attribute mappers for a SAML provider.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/saml/providers/{alias}

Method

GET

Request Body

No parameters.

Path Parameters

• alias: Alias of the SAML provider that you want to list. This is a mandatory field.

Result

This API lists all attribute mappers for a SAML provider.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/saml/providers/azure-ad-saml/mappers" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

[
  {
    "id": "mapper-uuid",
    "name": "email-mapper",
    "identityProviderMapper": "saml-user-attribute-idp-mapper",
    "identityProviderAlias": "azure-ad-saml",
    "config": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
]

Create SAML Attribute Mappers Endpoint

This API enables you to create attribute mappers for a SAML provider.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/saml/providers/{alias}

Method

POST

Request Body

No parameters.

Path Parameters

• alias: Alias of the SAML provider that you want to list. This is a mandatory field.

Result

This API lists all attribute mappers for a SAML provider.

Sample Request

{
  "attributeName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
  "mapperType": "saml-user-attribute-idp-mapper",
  "name": "email-mapper",
  "syncMode": "INHERIT",
  "userAttribute": "email"
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "message": "Attribute mapper created successfully",
  "mapperId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Delete SAML Attribute Mappers Endpoint

This API delete an attribute mappers for a SAML provider.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/saml/providers/{alias}

Method

DELETE

Request Body

No parameters.

Path Parameters

• alias: Alias of the SAML provider that you want to list. This is a mandatory field.
• mapper_id:

Result

This API deletes all attribute mappers for a SAML provider.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/saml/providers/azure-ad-saml/mappers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "status": "deleted",
  "mapperId": "mapper-uuid",
  "alias": "azure-ad-saml"
}

Password Policy

The following section lists the commonly used APIs for managing Password Policy.

Get Password Policy

This API allows you to get current password policy configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/passwordpolicy

Method

GET

Request Body

No parameters.

Path Parameters

No parameters.

Result

This API gets current password policy configuration.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/passwordpolicy" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "policy": {
    "digits": 1,
    "forceExpiredPasswordChange": 365,
    "hashAlgorithm": "pbkdf2-sha256",
    "hashIterations": 27500,
    "length": 8,
    "lowerCase": 1,
    "maxAuthAge": 3600,
    "maxLength": 64,
    "notContainsUsername": true,
    "notEmail": true,
    "notUsername": true,
    "passwordAge": 365,
    "passwordHistory": 3,
    "recoveryCodesWarningThreshold": 3,
    "regexPattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).*$",
    "specialChars": 1,
    "upperCase": 1
  }
}

Update Password Policy

This API allows you to update password policy configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/passwordpolicy

Method

PUT

Request Body

No parameters.

Path Parameters

No parameters.

Result

This API updates the password policy configuration.

Sample Request

{
  "policy": {
    "digits": 2,
    "forceExpiredPasswordChange": 90,
    "length": 10,
    "lowerCase": 1,
    "notUsername": true,
    "passwordHistory": 5,
    "specialChars": 1,
    "upperCase": 1
  }
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
  "policy": {
    "digits": 1,
    "forceExpiredPasswordChange": 365,
    "hashAlgorithm": "pbkdf2-sha256",
    "hashIterations": 27500,
    "length": 8,
    "lowerCase": 1,
    "maxAuthAge": 3600,
    "maxLength": 64,
    "notContainsUsername": true,
    "notEmail": true,
    "notUsername": true,
    "passwordAge": 365,
    "passwordHistory": 3,
    "recoveryCodesWarningThreshold": 3,
    "regexPattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).*$",
    "specialChars": 1,
    "upperCase": 1
  }
}

Microsoft Entra ID Federation Configuration

Microsoft Entra ID is a cloud-based identity and access management service. It manages your cloud and on-premise applications and protects user identities and credentials. The following section lists the commonly used APIs for managing Microsoft Entra ID federation.

Get Entra ID configuration endpoint

This API enables you to list the current Entra ID configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/config

Method

GET

Request Body

No parameters

Result

This API retrieves the current Entra ID configuration.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"tenantId": "<Tenant_ID>",
"clientId": "<Client_ID>",
"enabled": true,
"createdAt": "2026-01-16T11:02:43.259928",
"updatedAt": "2026-01-20T13:26:41.303308"
}

Create Entra ID configuration endpoint

This API enables you to create an Entra ID configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/config

Method

POST

Request Body

• tenantID: Entra ID tenant ID.
• clientID: Entra ID application ID.
• clientSecret: Entra ID application client secret.
• enabled: Whether Entra ID configuration is enabled.

Result

This API creates an Entra ID configuration.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"\
  -H "Content-Type: application/json" \
  -d '{
  "tenantId": "<Tenant_ID>",
  "clientId": "<Client_ID>",
  "clientSecret": "<Kubernetes_client_secret>",
  "enabled": true
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "created",
"message": "string",
"config": {
  "tenantId": "<Tenant_ID>",
  "clientId": "CLient_ID",
  "enabled": true,
  "createdAt": "2026-01-16T11:02:43.259928",
  "updatedAt": "2026-01-20T13:26:41.303308"
}
}

Update Entra ID configuration endpoint

This API enables you to update the Entra ID configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/config

Method

PUT

Request Body

• tenantID: Entra ID tenant ID.
• clientID: Entra ID application ID.
• clientSecret: Entra ID application client secret.
• enabled: Whether Entra ID configuration is enabled. It can have one of the following values:
  • true: Entra ID configuration is enabled.
  • false: Entra ID configuration is not enabled.

Result

This API updates the current Entra ID configuration.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"\
  -H "Content-Type: application/json" \
  -d '{
  "clientId": "r1290385-00eb-43d4-b452-e4dc25b55c54",
  "clientSecret": "ADC7Q~-PXz3kthHgldpNXLcBoYy_L0rTWRn2facz",
  "enabled": true,
  "tenantId": "2e56943b-6c92-446a-81b4-ead9ab5c5e0c"
}
'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "created",
"message": "Entra ID configuration created successfully",
"config": {
  "tenantId": "2e56943b-6c92-446a-81b4-ead9ab5c5e0c",
  "clientId": "r1290385-00eb-43d4-b452-e4dc25b55c54",
  "enabled": true,
  "createdAt": "2026-02-03T09:56:20.244693",
  "updatedAt": "2026-02-03T09:56:20.244865"
}
}

Delete Entra ID configuration endpoint

This API enables you to delete an Entra ID configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/config

Method

DELETE

Request Body

No parameters

Result

This API deletes a Microsoft Entra ID configuration.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "deleted",
"message": "Entra ID configuration deleted successfully"
}

Test Entra ID connection endpoint

This API enables you to test an Entra ID connection endpoint.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/config/test

Method

POST

Request Body

• tenantID: Entra ID tenant ID.
• clientID: Entra ID application ID.
• clientSecret: Entra ID application client secret.
• useStoredConfig: Specify true to test the currently stored configuration. Speicify false to provide credentials for testing without storing.

Result

This API tests an Entra ID endpoint connection.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config/test" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "tenantId": "<Tenant_ID>",
  "clientId": "<Client_ID>",
  "clientSecret": "<Client_secret>",
  "useStoredConfig": false
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "success",
"message": "string",
"tenantId": "<Tenant_ID>",
"userCount": 0,
"testTimestamp": "2026-01-20T13:26:41.303308"
}

Search Entra ID users endpoint

This API enables you to search Entra ID users using the stored configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/users/search

Method

POST

Request Body

• searchQuery: Specify the name of the Entra ID user to search for specific users. Specify null to retrieve a list of all the Entra ID users.

Query Parameters

• max: Maximum number of entries that can retrieved.
• first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API searches Entra ID users.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/users/search?max=100&first=0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "searchQuery": "john"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "success",
"message": "Found 1 users matching 'john'",
"users": [
  {
    "userPrincipalName": "John", 
   "email": "john.doe@protegrity.com", 
    "firstName": "John", 
    "lastName": "Doe"
  }
],
"totalCount": 1,
"searchTimestamp": "2026-02-03T10:03:48.722709"
}

Import Entra ID users with roles endpoint

This API enables you to import Entra ID users with assigned roles.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/users

Method

POST

Request Body

• users: Array of user objects to import. Each user must have either the userPrincipalName or email parameter specified.
  • userPrincipalName: User principal name from Entra ID.
  • email: Primary email address of the user.
  • firstName: First name of the user. This is an optional parameter.
  • lastName: Last name of the user. This is an optional parameter.
  • roles: An array that specifies the roles assigned to the user.
  • identityProviders: An array that specifies the identity providers to be associated with the user. This is an optional field. For example, you can specify the value as AWS-IDP or AZURE-IDP.
• dryRun: If true, validates the import without actually creating users. The default value is false.

Result

This API imports Entra ID users with assigned roles.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/users" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
        {
            "userPrincipalName": "admin@company.com",
            "email": "admin@company.com",
            "firstName": "Admin",
            "lastName": "User",
            "roles": ["administrator", "user"],
            "identityProviders": ["AWS-IDP"]
        },
        {
            "userPrincipalName": "user@company.com",
            "email": "user@company.com",
            "firstName": "Regular",
            "lastName": "User",
            "roles": ["user"]
        }
    ],
    "dryRun": true
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "success",
"message": "Users imported successfully",
"totalUsers": 10,
"successCount": 9,
"failedCount": 1
}

Search Entra ID groups endpoint

This API enables you to search for Entra ID groups using stored configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/groups/search

Method

POST

Request Body

• searchQuery: Specify the name of the Entra ID group to search for specific groups. Specify null to retrieve a list of all the Entra ID groups.

Query Parameters

• max: Maximum number of entries that can retrieved.
• first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API searches for Entra ID groups.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/groups/search" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "searchQuery": "admin"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "success",
"message": "string",
"groups": [
  {
    "id": "1",
    "displayName": "admin"
  }
],
"totalCount": 0,
"searchTimestamp": "2026-01-20T13:26:41.303308"
}

Search Entra ID group members endpoint

This API enables you to search for Entra ID group members using stored configuration.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/groups/members/search

Method

POST

Request Body

• groupID: ID of the searched group. This value is case-sensitive and must be an exact match.
• searchQuery: Specify the name of the Entra ID group member to search for a specific member. If this parameter is not specified, then the API retrieve a list of all the members of the Entra ID group.

Result

This API searches for Entra ID group members.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/groups/members/search" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "groupId": "12345678-1234-1234-1234-123456789012",
  "searchQuery": "john"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "success",
"message": "string",
"groupId": "12345678-1234-1234-1234-123456789012",
"groupName": "admin",
"members": [
  {
    "userPrincipalName": "John",
    "email": "john.doe@protegrity.com",
    "firstName": "John",
    "lastName": "Doe"
  }
],
"totalCount": 0,
"searchTimestamp": "2026-01-20T13:26:41.303308"
}

Import Entra ID groups endpoint

This API enables you to import Entra ID groups into the application.

Base URL

https://<FQDN>/pty/<version>/<API>

Path

/federation/entra/groups

Method

POST

Request Body

• groups: Array of group objects to import. Each user must have the id or displayName parameters specified.
  • id: Unique group identifier from Entra ID. This is a required field.
  • displayName: Group display name. This is a required field.
  • description: Group description.
  • importMembers: Specify true to import group members. The default value is false.
  • memberRoles: An array that specifies the roles assigned to group members.
  • identityProviders: An array that specifies the identity providers to be associated with the group. This is an optional field. For example, you can specify the value as AWS-IDP or AZURE-IDP.
• dryRun: If true, validates the import without actually creating users. The default value is false.

Result

This API imports Entra ID groups.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/groups" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "groups": [
    {
      "id": "12345678-1234-1234-1234-123456789012",
      "displayName": "Administrators",
      "description": "Administrative users group",
      "importMembers": true,
      "memberRoles": [
        "user",
        "member"
      ],
      "identityProviders": ["AWS-IDP"]
    }
  ],
  "dryRun": true
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

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

Response body

{
"status": "success",
"message": "Groups imported successfully",
"totalGroups": 5,
"successCount": 5,
"totalMembersImported": 25
}

5 - Using the Policy Management REST APIs

Important: The Policy Management REST APIs will work only after you have installed the 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.

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.

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.

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.

Path

/pim/roles

Method

POST

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.

Path

/pim/roles

Method

POST

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.

For more information about creating a policy, refer to the section Creating Policies.

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.

Path

/pim/policies

Method

POST

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.

Path

/pim/policies/1/rules

Method

POST

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.

Path

/pim/datastores

Method

POST

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 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://{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.

Path

/pim/datastores/{dataStoreUid}/deploy

Method

POST

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.

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://{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.

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.

6 - Using the Encrypted Resilient Package REST APIs

Important: The Encrypted Resilient Package REST API will work only after you have installed the Policy Workbench. For more information about installing Policy Workbench, refer to the section Installing Policy Workbench.

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 AI Team Edition.

• The user accessing this API must have the workbench_deployment_immutablepackage_export permission.
  For more information about the roles and permissions required, refer to the section Workbench Roles and Permissions.

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.

Exporting Resilient Package Using GET Method

This API request exports the resilient package that can be used with resilient protectors. You can use 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.

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

Base URL

https://<FQDN>/pty/v1/rps

Path

/export

Method

GET

CURL request syntax

Export API

curl -H "Authorization: Bearer <TOKEN>" -X GET https://<FQDN>/pty/v1/rps/export/<fingerprint>?version=1&coreVersion=1 -H "Content-Type: application/json" -o rps.json

In this command, TOKEN indicates the JWT token used for authenticating the API.
For more information about creating a JWT token, refer to the section Generate token.

Query Parameters

fingerprint

Specify the fingerprint of the Data Store Export Key. The fingerprint is used to identify which Data Store to export and which export key to use for protecting the resilient package. The user with the Security Officer permissions must share the fingerprint of the Export Key with the user who is executing this API. For more information about obtaining the fingerprint of the Data Store Export Key, refer to step 7 of the section Adding Export Key.

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.

Sample CURL request

Export API

curl -H "Authorization: Bearer $<TOKEN>" -X GET https://<FQDN>/pty/v1/rps/export/a7fdbc0cccc954e00920a4520787f0a08488db8e0f77f95aa534c5f80477c03a?version=1&coreVersion=1 -H "Content-Type: application/json" -o rps.json

This sample request uses the JWT token authentication.

Sample response

The rps.json file is exported using the public key associated with the specified fingerprint.

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

7 - Roles and Permissions

Roles are templates that include permissions and users can be assigned to one or more roles. All users in the appliance must be associated with a role.

The roles packaged with PPC are as follows:

The capabilities of a role are defined by the permissions attached to the role. Though roles can be created, modified, or deleted from the appliance, permissions cannot be edited. The permissions that are available to map with a user and packaged with PPC as default permissions are as follows: