Using the Common REST API Endpoints

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

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

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

REST API	Description	Base URL <Version>
pim	Policy Management	v2
rps	Encrypted Resilient Package	v1
auth	Authentication and Token Management	v1

Common REST API Endpoints

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

REST API	Description
/version	Retrieves the application version.
/buildVersion	Retrieves the full build version string including pre-release and build metadata.
/health	Retrieves the health information for the Protegrity REST APIs and identifies whether the corresponding service is running.
/doc	Retrieves the API specification document.
/log	Retrieves the current log level of the REST API service logs.
/log	Changes the log level for the REST API service during run-time. The level set through this resource is persisted until the corresponding service is restarted. This log level overrides the log level defined in the configuration.
/ready	Retrieves the information for the Protegrity REST APIs to identify whether the corresponding service can handle requests.
/live	Retrieves the information for the Protegrity REST APIs to determine whether the corresponding service should be restarted.

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 saved to the output file name specified in the command, rather than being displayed in the terminal. 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 <Token>"

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.

Log Level	Description	When to Use
SEVERE	Indicates a critical failure that prevents normal operation.	Use when the service encounters a fatal error that requires immediate attention, such as an unrecoverable system failure.
WARNING	Indicates a potential problem that does not stop the service but may require attention.	Use when an unexpected situation occurs that could lead to errors if not addressed.
INFO	Provides general informational messages about the progress of the service.	Use for routine operational messages, such as service startup, shutdown, or key processing milestones.
CONFIG	Captures static configuration details.	Use to log configuration settings and parameters at service startup for diagnostic purposes.
FINE	Provides general tracing and debugging information.	Use for basic debugging when troubleshooting issues.
FINER	Provides more detailed tracing than FINE, including method entry and exit points.	Use for in-depth debugging when more granular trace information is needed.
FINEST	Provides the most detailed and verbose tracing output.	Use only when exhaustive debugging information is required, as this level generates a high volume of log data.

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 - Environment 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

This API request retrieves the readiness status of the REST API service and identifies whether the corresponding service is ready to handle requests.

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

This API request retrieves the liveness status of the REST API service and determines whether the corresponding service should be restarted.

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

Feedback

Was this page helpful?

Last modified : July 29, 2026